@Part[Io, Root = "CLM.MSS"]
@Comment{Chapter of Common Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇


@MyChapter[Input/Output]
@Label[IO]

@clisp provides a rich set of facilities for performing input/output.
All input/output operations are performed on streams of various kinds.
This chapter is devoted to stream data transfer operations.
Streams are discussed in chapter @ref[STREAM], and
ways of manipulating files through streams are discussed in
chapter @ref[FILES].

While there is provision for reading and writing binary data,
most of the I/O operations in @clisp read or write characters.
There are simple primitives for reading and writing single characters
or lines of data.  The @f[format] function can perform complex
formatting of output data, directed by a control string
in manner similar to a @fortran @c[FORMAT] statement
or a @pl1 @c[put edit] statement.  The most useful I/O operations,
however, read and write printed representations of arbitrary
@xlisp objects.

@Section[Printed Representation of @xlisp Objects]

@xlisp objects in general are not text strings, but complex data structures.
They have very different properties from text strings as a consequence of
their internal representation.  However, to make it possible to get at
and talk about @xlisp objects, @xlisp provides a representation of
most objects in the form of printed text; this is called the @i[printed
representation], which is used for input/output purposes and in the
examples throughout this manual.  Functions such as @Funref[print] take a
@xlisp object and send the characters of its printed representation to a
stream.  The collection of routines that does this is known as the
(@xlisp) @i[printer].  The @f[read] function takes characters from a
stream, interprets them as a printed representation of a @xlisp object,
builds that object, and returns it; the collection of routines
that does this is called the (@xlisp) @i[reader].
@Index[printer]
@Index[printed representation]
@Index[reader]

Ideally, one could print a @xlisp object and then read the printed
representation back in, and so obtain the same identical object.
In practice this is difficult and for some purposes not even desirable.
Instead, reading a printed representation produces an object
that is (with obscure technical exceptions)
@Funref[equal] to the originally printed object.

Most @xlisp objects have more than one possible printed representation.
For example, the integer twenty-seven can be written in any of these ways:
@Lisp
27    27.    #o33    #x1B    #b11011    #.(* 3 3 3)    81/3
@Endlisp
A list of two symbols @f[A] and @f[B] can be printed in many ways:
@Lisp
    (A B)    (a b)    (  a  b )    (\A |B|)
    (|\A|
  B
)
@Endlisp
The last example, which is spread over three lines, may be ugly, but it
is legitimate.  In general, wherever whitespace is permissible in a printed
representation, any number of spaces and newlines may appear.

When @f[print] produces a printed representation, it must choose arbitrarily
from among many possible printed representations.  It attempts to choose
one that is readable.  There are a number of global variables that can
be used to control the actions of @f[print], and a number of different
printing functions.

This section describes in detail what is the standard printed
representation for any Lisp object, and also describes how @f[read] operates.

@Subsection[What the Read Function Accepts]
@label[READER]
@Index[reader]
The purpose of the @xlisp reader is to accept characters, interpret them
as the printed representation of a @xlisp object, and construct and
return such an object.  The reader cannot accept everything that the
printer produces; for example, the printed representations of compiled
code objects cannot be read in.  However, the reader has
many features that are not used by the output of the printer at all,
such as comments, alternative representations, and convenient
abbreviations for frequently used but unwieldy constructs.  The reader is
also parameterized in such a way that it can be used as a lexical
analyzer for a more general user-written parser.

The reader is organized as a recursive-descent parser.
Broadly speaking,
the reader operates by reading a character from
the input stream and treating it in one of three ways.
Whitespace characters serve as separators but are otherwise
ignored.  Consituent and escape characters are accumulated
to make a @i[token], which is then interpreted as a number or symbol.
Macro characters trigger the invocation of functions (possibly
user-supplied) that can perform arbitrary parsing actions,
including recursive invocation of the reader.

More precisely,
when the reader is invoked, it reads a single character from the input stream
and dispatches according to the syntactic type of that character.
Every character that can appear in the input stream
must be of exactly one of the following kinds:
@i[illegal],
@i[whitespace],
@i[constituent],
@i[single escape],
@i[multiple escape], or
@i[macro].
Macro characters are further divided
into the types @i[terminating] and @i[non-terminating] (of tokens).
(Note that macro characters have nothing whatever to do with macros
in their operation.  There is a superficial similarity in that macros allow
the user to extend the syntax of @clisp at the level of forms,
while macro characters allow the user to extend the syntax at the
level of characters.)
Constituents additionally have one or more attributes,
the most important of which is @i[alphabetic]; these attributes are discussed
further in section @ref[PARSE-TOKENS-SECTION].

The parsing of @clisp expressions is discussed in terms of these
syntactic character types because the types of individual characters
are not fixed
but may be altered by the user (see @Funref[set-syntax-from-char]
and @Funref[set-macro-character]).
The characters of the standard character set initially have the
syntactic types shown in Table @Ref[Standard-Character-Syntax-Table].
Note that
the brackets, braces, question mark, and exclamation point
(that is, @f{@lbracket@;⎇, @f{@rbracket@;⎇, @f[@lbrace@;],
@f[@rbrace@;], @f[?],
and @f[!]) are normally defined to be constituents, but they
are not used for any purpose in standard @clisp syntax and do not occur
in the names of built-in @clisp functions or variables.
These characters are explicitly reserved to the user.
The primary intent
is that they be used as macro characters; but a user might choose,
for example, to make @f[!] be a @i[single escape] character
(as it is in @psl).

The algorithm performed by the @clisp reader is roughly as follows:
@Begin[Enumerate]
If at end of file, perform end-of-file processing (as specified
by the caller of the @Funref[read] function).
Otherwise,
read one character from the input stream, call it @i[x], and
dispatch according to the syntactic type of @i[x] to one
of steps @ref[READER-ILLEGAL] to @ref[READER-CONSTITUENT].
@tag[READER-START]

If @i[x] is an @i[illegal] character, signal an error.
@tag[READER-ILLEGAL]

If @i[x] is a @i[whitespace] character,
then discard it and go back to step @ref[READER-START].
@tag[READER-WHITESPACE]

@Begin[Multiple]
If @i[x] is a @i[macro] character (at this point the
distinction between @i[terminating] and @i[non-terminating] macro characters
does not matter), then execute the function associated
with that character.  The function may return zero values or one value
(see @Funref[values]).

The macro-character function may of course read characters from the input
stream; if it does, it will see those characters following the macro
character.  The function may even invoke the reader recursively.
This is how the macro character @f[(] constructs a list:
by invoking the reader recursively to read the elements of the list.

If one value is returned, then return that value as the result of the
read operation; the algorithm is done.
If zero values are returned, then go back to step @ref[READER-START].
@End[Multiple]

If @i[x] is a @i[single escape] character (normally @f[\]),
then read the next character and call it @i[y]
(but if at end of file, signal an error instead).
Ignore the usual syntax of @i[y]
and pretend it is a @i[constituent] whose only attribute is
@i[alphabetic].
(If @i[y] is a lowercase character, leave it alone;
do not replace it with the corresponding uppercase character.)
Use @i[y] to begin a token, and go to step
@ref[READER-PLAIN-TOKEN].

If @i[x] is a @i[multiple escape] character (normally @f[|]),
then begin a token (initially
containing no characters) and go to step @ref[READER-MULTI-TOKEN].

If @i[x] is a @i[constituent] character, then it begins an extended token.
@tag[READER-CONSTITUENT]@}
After the entire token is read in, it will be interpreted
either as representing a @xlisp object such as a symbol or number
(in which case that object is returned as the result of the read operation),
or as being of illegal syntax (in which case an error is signalled).
If @i[x] is a lowercase character, replace it with the
corresponding uppercase character.
Use @i[x] to begin a token, and go on to step
@ref[READER-PLAIN-TOKEN].

@Begin[Multiple]
(At this point a token is being accumulated, and an even number
of @i[multiple escape] characters have been encountered.)
@tag[READER-PLAIN-TOKEN]@}

If at end of file, go to step @ref[READER-TOKEN-END].
Otherwise, read a character (call it @i[y]), and
perform one of the following actions according to its syntactic type:
@Begin[Itemize]
If @i[y] is a @i[constituent] or @i[non-terminating macro] character,
then do the following.
If @i[y] is a lowercase character, replace it with the
corresponding uppercase character.
Append @i[y] to the token being built,
and repeat step @ref[READER-PLAIN-TOKEN].

If @i[y] is a @i[single escape] character, then read the next character
and call it @i[z]
(but if at end of file, signal an error instead).
Ignore the usual syntax of @i[z]
and pretend it is a @i[constituent] whose only attribute is
@i[alphabetic].
(If @i[z] is a lowercase character, leave it alone;
do not replace it with the corresponding uppercase character.)
Append @i[z] to the token being built,
and repeat step @ref[READER-PLAIN-TOKEN].

If @i[y] is a @i[multiple escape] character,
then go to step @ref[READER-MULTI-TOKEN].

If @i[y] is an @i[illegal] character, signal an error.

If @i[y] is a @i[terminating macro] character, then it terminates
the token.  First ``unread'' the character @i[y]
(see @Funref[unread-char]), and then go to step @ref[READER-TOKEN-END].

If @i[y] is a @i[whitespace] character, then it terminates
the token.  First ``unread'' the character @i[y]
if appropriate (see @Funref[read-preserving-whitespace]),
and then go to step @ref[READER-TOKEN-END].
@End[Itemize]
@End[Multiple]

@Begin[Multiple]
(At this point a token is being accumulated, and an odd number
of @i[multiple escape] characters have been encountered.)
@tag[READER-MULTI-TOKEN]@}

If at end of file, signal an error.
Otherwise, read a character (call it @i[y]), and
perform one of the following actions according to its syntactic type:
@Begin[Itemize]
If @i[y] is a @i[constituent], @i[macro], or @i[whitespace]
character, then ignore the usual syntax of that character
and pretend it is a @i[constituent] whose only attribute is
@i[alphabetic].
(If @i[y] is a lowercase character, leave it alone;
do not replace it with the corresponding uppercase character.)
Append @i[y] to the token being built,
and repeat step @ref[READER-MULTI-TOKEN].

If @i[y] is a @i[single escape] character, then read the next character
and call it @i[z]
(but if at end of file, signal an error instead).
Ignore the usual syntax of @i[z]
and pretend it is a @i[constituent] whose only attribute is
@i[alphabetic].
(If @i[z] is a lowercase character, leave it alone;
do not replace it with the corresponding uppercase character.)
Append @i[z] to the token being built,
and repeat step @ref[READER-MULTI-TOKEN].

If @i[y] is a @i[multiple escape] character,
then go to step @ref[READER-PLAIN-TOKEN].

If @i[y] is an @i[illegal] character, signal an error.
@End[Itemize]
@End[Multiple]

An entire token has been accumulated.  Interpret it as representing
a @xlisp object and return that object as the result
of the read operation, or signal an error if the token
is not of legal syntax.
@tag[READER-TOKEN-END]
@End[Enumerate]

As a rule, a @i[single escape] character never stands for itself but always
serves to cause the following character to be treated as a simple alphabetic
character.  A @i[single escape] character can be included in a token only
if preceded by another @i[single escape] character.

A @i[multiple escape] character also never stands for itself.  The characters
between a pair of @i[multiple escape] characters are all treated as
simple alphabetic characters, except that @i[single escape] and
@i[multiple escape] characters must nevertheless be preceded by
a @i[single escape] character to be included.

@Incompatibility{In @maclisp, the @f[|] character is implemented
as a macro character that reads characters up to the next unescaped
@f[|] and then makes a token; no characters are ever read beyond
the second @f[|] of a matching pair.
In @clisp, the second @f[|] does not terminate the token being read
but merely reverts to the ordinary (rather than multiple-escape) mode
of token accumulation.  This results in some differences in the way
certain character sequences are interpreted.  For example,
the sequence @f[|foo||bar|] would be read in @maclisp
as two distinct tokens @f[|foo|] and @f[|bar|], whereas in @clisp
it would be treated as a single token equivalent to @f[|foobar|].
The sequence @f[|foo|bar|baz|] would be read in @maclisp
as three distinct tokens @f[|foo|], @f[bar], and @f[|baz|], whereas in @clisp
it would be treated as a single token equivalent to @f[|fooBARbaz|];
note that the middle three lowercase letters are converted to
uppercase letters as they
do not fall within a matching pair of vertical bars.

One reason for the different treatment of @f[|] in @clisp lies
in the syntax for package-qualified symbol names.  A sequence such as
@f[|foo:bar|] ought to be interpreted as a symbol whose name is
@f[foo:bar]; the colon should be treated as a simple alphabetic
character because it lies within a pair of vertical bars.  The symbol
@f[|bar|] within the package @f[|foo|] can be notated, not as @f[|foo:bar|],
but as @f[|foo|:|bar|]; the colon can serve as a package marker because
it falls outside the vertical bars, and yet the notation is treated as a single
token thanks to the new rules adopted in @clisp.⎇

In @maclisp, the parentheses are treated as
additional character types.  In @clisp they are simply @i[macro] characters,
as described in section @ref[MACRO-CHARACTERS-SECTION].

What @maclisp calls a ``single character object''
(tokens of type @i[single]) are not provided for explicitly in @clisp.
They can be viewed as simply a kind of macro character.
That is, the effect of
@lisp
(setsyntax '$ 'single @false)
(setsyntax '% 'single @false)
@endlisp
in @maclisp can be achieved in @clisp by
@lisp
(defun single-macro-character (stream char)
  (declare (ignore stream))
  (intern (string char)))

(set-macro-character '$ #'single-macro-character)
(set-macro-character '% #'single-macro-character)
@Endlisp
⎇

@Begin[FullPageTable]
@Mline[]
@Caption[Standard Character Syntax Types]
@Tag[Standard-Character-Syntax-Table]
@Begin[Format]
@tabset[+2.5in,+2in]
<tab>@f[  ]@i[whitespace]@\<page>@f[  ]@i[whitespace]@\<newline>@f[  ]@i[whitespace]
<space>@f[  ]@i[whitespace]@\@f[@@  ]@i[constituent]@\@f[@bq  ]@i[terminating macro]
@f[!  ]@i[constituent]*@\@f[A  ]@i[constituent]@\@f[a  ]@i[constituent]
@f["  ]@i[terminating macro]@\@f[B  ]@i[constituent]@\@f[b  ]@i[constituent]
@f[#  ]@i[non-terminating macro]@\@f[C  ]@i[constituent]@\@f[c  ]@i[constituent]
@f[$  ]@i[constituent]@\@f[D  ]@i[constituent]@\@f[d  ]@i[constituent]
@f[%  ]@i[constituent]@\@f[E  ]@i[constituent]@\@f[e  ]@i[constituent]
@f[&  ]@i[constituent]@\@f[F  ]@i[constituent]@\@f[f  ]@i[constituent]
@f['  ]@i[terminating macro]@\@f[G  ]@i[constituent]@\@f[g  ]@i[constituent]
@f[(  ]@i[terminating macro]@\@f[H  ]@i[constituent]@\@f[h  ]@i[constituent]
@f[)  ]@i[terminating macro]@\@f[I  ]@i[constituent]@\@f[i  ]@i[constituent]
@f[*  ]@i[constituent]@\@f[J  ]@i[constituent]@\@f[j  ]@i[constituent]
@f[+  ]@i[constituent]@\@f[K  ]@i[constituent]@\@f[k  ]@i[constituent]
@f[,  ]@i[terminating macro]@\@f[L  ]@i[constituent]@\@f[l  ]@i[constituent]
@f[-  ]@i[constituent]@\@f[M  ]@i[constituent]@\@f[m  ]@i[constituent]
@f[.  ]@i[constituent]@\@f[N  ]@i[constituent]@\@f[n  ]@i[constituent]
@f[/  ]@i[constituent]@\@f[O  ]@i[constituent]@\@f[o  ]@i[constituent]
@f[0  ]@i[constituent]@\@f[P  ]@i[constituent]@\@f[p  ]@i[constituent]
@f[1  ]@i[constituent]@\@f[Q  ]@i[constituent]@\@f[q  ]@i[constituent]
@f[2  ]@i[constituent]@\@f[R  ]@i[constituent]@\@f[r  ]@i[constituent]
@f[3  ]@i[constituent]@\@f[S  ]@i[constituent]@\@f[s  ]@i[constituent]
@f[4  ]@i[constituent]@\@f[T  ]@i[constituent]@\@f[t  ]@i[constituent]
@f[5  ]@i[constituent]@\@f[U  ]@i[constituent]@\@f[u  ]@i[constituent]
@f[6  ]@i[constituent]@\@f[V  ]@i[constituent]@\@f[v  ]@i[constituent]
@f[7  ]@i[constituent]@\@f[W  ]@i[constituent]@\@f[w  ]@i[constituent]
@f[8  ]@i[constituent]@\@f[X  ]@i[constituent]@\@f[x  ]@i[constituent]
@f[9  ]@i[constituent]@\@f[Y  ]@i[constituent]@\@f[y  ]@i[constituent]
@f[:  ]@i[constituent]@\@f[Z  ]@i[constituent]@\@f[z  ]@i[constituent]
@f[;  ]@i[terminating macro]@\@f{[  ⎇@i[constituent]*@\@f[{  ]@i[constituent]*
@f[<  ]@i[constituent]@\@f[\  ]@i[single escape]@\@f[|  ]@i[multiple escape]
@f[=  ]@i[constituent]@\@f{]  ⎇@i[constituent]*@\@f[⎇  ]@i[constituent]*
@f[>  ]@i[constituent]@\@f[↑  ]@i[constituent]@\@f[@tilde  ]@i[constituent]
@f[?  ]@i[constituent]*@\@f[@underscore@;  ]@i[constituent]@\<rubout>@f[  ]@i[constituent]
<backspace>@f[  ]@i[constituent]@\<return>@f[  ]@i[whitespace]@\<linefeed>@f[  ]@i[whitespace]
@End[Format]
@Begin[Text, Font Smallbodyfont, Indent 0]
* The characters marked with an asterisk are initially constituents,
but are reserved to the user for use as macro characters or for
any other desired purpose.
@End[Text]
@Mline[]
@End[FullPageTable]

@Begin[Table]
@Mline[]
@Caption[Actual Syntax of Numbers]
@Tag[Number-Syntax-Table]
@Begin[Format, leftmargin +0.5in]
@tabclear
@i[number] ::= @i[integer] @mor @i[ratio] @mor @i[floating-point-number]
@i[integer] ::= @Mopt<@i[sign]> @Mplus<@i[digit]> @Mopt<@i[decimal-point]>
@i[ratio] ::= @Mopt<@i[sign]> @Mplus<@i[digit]> @f[/] @Mplus<@i[digit]>
@i[floating-point-number] ::=@↑ @Mopt<@i[sign]> @Mstar<@i[digit]> @i[decimal-point] @Mplus<@i[digit]> @Mopt<@i[exponent]>
@>@mor@\ @Mopt<@i[sign]> @Mplus<@i[digit]> @mopt'@i[decimal-point] @Mstar<@i[digit]>' @i[exponent]
@i[sign] ::= @f[+] @mor @f[-]
@i[decimal-point] ::= @f[.]
@i[digit] ::= @f[0] @mor @f[1] @mor @f[2] @mor @f[3] @mor @f[4] @mor @f[5] @mor @f[6] @mor @f[7] @mor @f[8] @mor @f[9]
@i[exponent] ::= @i[exponent-marker] @Mopt<@i[sign]> @Mplus<@i[digit]>
@i[exponent-marker] ::= @f[e] @mor @f[s] @mor @f[f] @mor @f[d] @mor @f[l] @mor @f[E] @mor @f[S] @mor @f[F] @mor @f[D] @mor @f[L]
@End[Format]
@Begin[Text, font smallbodyfont, indent 0]
The notation @Mstar<@i[x]> means zero or more occurrences
of @i[x], the notation @Mplus<@i[x]> means one or more occurrences
of @i[x], and the notation @Mopt<@i[x]> means zero or one occurrences
of @i[x].
@End[Text]
@Mline[]
@End[Table]

@Subsection[Parsing of Numbers and Symbols]
@label[PARSE-TOKENS-SECTION]

When an extended token is read, it is interpreted as a number or symbol.
In general, the token is interpreted as a number if it satisfies
the syntax for numbers specified in Table @Ref[NUMBER-SYNTAX-TABLE];
this is discussed in more detail below.

The characters of the extended token may serve various syntactic
functions as shown
in Table @Ref[Standard-Readtable-Attributes-Table], but it must be
remembered that any character included in a token under the control
of an escape character is treated as @i[alphabetic] rather than
according to the attributes shown in the table.
One consequence of this rule is that a whitespace, macro, or escape
character will always be treated as alphabetic within an extended token
because such a character cannot be included in an extended
token except under the control of an escape character.

To allow for extensions to the syntax of numbers, a
syntax for @i[potential numbers] is defined in @clisp that is
more general than the actual syntax for numbers.
Any token that is not a potential number and does not consist
entirely of dots will always be taken to be a symbol,
now and in the future; programs may rely on this fact.
Any token that is a potential number but does not fit the
actual number syntax defined below is a @Def[reserved token] and
has an implementation-dependent interpretation;
an implementation may signal an error, quietly treat the token
as a symbol, or take some other action.  Programmers should avoid
the use of such reserved tokens.  (A symbol whose name looks like a reserved
token can always be written using one or more escape characters.)

A token is a potential number if it satisfies the following
requirements:
@Begin[Itemize]
It consists entirely of digits, signs (@f[+] or @f[-]),
ratio markers (@f[/]), decimal points (@f[.]), extension characters
(@f[↑] or @f[←]), and number markers.  (A number marker is
a letter.  Whether a letter may be treated as a number marker depends
on context, but no letter that is adjacent to another letter may ever be
treated as a number marker.  Floating-point exponent markers are instances
of number markers.)

It contains at least one digit.  (Letters may be considered to be
digits, depending on the value of @Varref[read-base], but only
in tokens containing no decimal points.)

It begins with a digit, sign, decimal point, or extension character.

It does not end with a sign.
@End[Itemize]
As examples, the following tokens are potential numbers,
but they are @i[not] actually numbers as defined below, and so are
reserved tokens.  (They do indicate some interesting possibilities
for future extensions.)
@lisp
@tabdivide[5]
1b5000@\777777q@\1.7J@\-3/4+6.7J@\12/25/83
27↑19@\3↑4/5@\6//7@\3.1.2.6@\↑-43↑
3.141←592←653←589←793←238←4@\-3.7+2.6i-6.17j+19.6k
@endlisp
The following tokens are @i[not] potential numbers but are always
treated as symbols:
@lisp
@tabdivide[5]
/@\/5@\+@\1+@\1-
foo+@\ab.cd@\←@\↑@\↑/-
@endlisp
The following tokens are potential numbers if the value of
@var[read-base] is @f[16] (an abnormal situation), but they are
always treated as symbols if the value of @var[read-base]
is @f[10] (the usual value):
@lisp
@tabdivide[5]
bad-face@\25-dec-83@\a/b@\fad←cafe@\f↑
@endlisp
It is possible for there to be an ambiguity as to whether
a letter should be treated as a digit or as a number marker.
In such a case, the letter is always treated as a digit
rather than as a number marker.

Note that the printed representation for a potential
number may not contain any escape characters.
An escape character robs the following character of all syntactic
qualities, forcing it to be strictly alphabetic and therefore unsuitable
for use in a potential number.  For example,
all of the following representations are interpreted as symbols, not numbers:
@lisp
\256   25\64   1.0\E6   |100|   3\.14159   |3/4|   3\/4   5||
@endlisp
In each case, removing the escape character(s) would allow the token
to be treated as a number.

If a potential number can in fact
be interpreted as a number according to the @c[bnf]
syntax in Table @Ref[NUMBER-SYNTAX-TABLE], then a number object of the
appropriate type is constructed and returned.  It should be noted that in
a given implementation it may be that not all tokens conforming to the
actual syntax for numbers can actually be converted into number objects.
For example, specifying too large or too small an exponent for a floating-point
number may make the number impossible to represent in the implementation.
Similarly, a ratio with denominator zero (such as @f[-35/000])
cannot be represented in @i[any] implementation.
In any such circumstance where
a token with the syntax of a number cannot be converted to an internal
number object, an error is signalled.  (On the other hand, an error
must not be signalled for specifying too many significant digits
for a floating-point number; an appropriately truncated or rounded
value should be produced.)

There is an omission in the syntax of numbers,
as described in Table @Ref[NUMBER-SYNTAX-TABLE],
in that the syntax does not account for the possible
use of letters as digits.
The radix used for reading integers and ratios is normally decimal.
However, this radix is actually determined by the value of
the variable @Varref[read-base], whose initial value is @f[10].
@Var[read-base] may take on any integral value between @f[2] and @f[36];
let this value be @i[n].  Then a token @i[x] is interpreted as
an integer or ratio in base @i[n] if it could be properly
so interpreted in the syntax @f[#@i[n]R@i[x]]
(see section @ref[SHARP-SIGN-MACRO-CHARACTER-SECTION]).
So, for example, if the value of @var[read-base] is @f[16],
then the printed representation
@lisp
(a small face in a bad place)
@endlisp
would be interpreted as if the following representation had
been read with @var[read-base] set to @f[10]:
@lisp
(10 small 64206 in 10 2989 place)
@endlisp
because four of the seven tokens in the list can be interpreted
as hexadecimal numbers.  This facility is intended to be used
in reading files of data that for some reason contain numbers
not in decimal radix; it may also be used for reading programs
written in @xlisp dialects (such as @maclisp) whose default number radix is not
decimal.  Non-decimal constants in @clisp programs
or portable @clisp data files should be written using
@f[#O], @f[#X], @f[#B], or @f[#@i[n]R] syntax.

When @Var[read-base] has a value greater than ten, an ambiguity
is introduced into the actual syntax for numbers because a letter can serve
as either a digit or an exponent marker; a simple example is @f[1E0]
when the value of @var[read-base] is @f[16].  The ambiguity is resolved
in accordance with the general principle that interpretation
as a digit is preferred to interpretation as a number marker.
The consequence in this case is that
if a token can be interpreted as either an integer or a floating-point
number, then it is taken to be an integer.

If a token consists solely of dots (with no escape characters), then an
error is signalled, except in one circumstance: if the token is a single
dot and occurs in a situation appropriate to ``dotted list'' syntax,
then it is accepted as a part of such syntax.  Signalling an error
catches not only misplaced dots in dotted list syntax, but also
lists that were truncated by @Varref[print-length] cutoff,
because such lists end with a three-dot sequence (@f[...]).
Examples:
@lisp
(a . b)		;@r[A dotted pair of @f[a] and @f[b]]
(a.b)		;@r[A list of one element, the symbol named @f[a.b]]
(a. b)		;@r[A list of two elements @f[a.] and @f[b]]
(a .b)		;@r[A list of two elements @f[a] and @f[.b]]
(a \. b)	;@r[A list of three elements @f[a], @f[.], and @f[b]]
(a |.| b)	;@r[A list of three elements @f[a], @f[.], and @f[b]]
(a \... b)	;@r[A list of three elements @f[a], @f[...], and @f[b]]
(a |...| b)	;@r[A list of three elements @f[a], @f[...], and @f[b]]
(a b . c)	;@r[A dotted list of @f[a] and @f[b] with @f[c] at the end]
.iot		;@r[The symbol whose name is @f[.iot]]
(. b)		;@r[Illegal; an error is signalled.]
(a .)		;@r[Illegal; an error is signalled.]
(a .. b)	;@r[Illegal; an error is signalled.]
(a . . b)	;@r[Illegal; an error is signalled.]
(a b c ...)	;@r[Illegal; an error is signalled.]
@endlisp

In all other cases, the token is construed to be the name of a symbol.
If there are any package markers
(colons) in the token, they divide the token into pieces used to
control the lookup and creation of the symbol.

If there is a single package marker, and it occurs at the beginning of the
token, then the token is interpreted as a keyword, that is, a symbol in the
@f[keyword] package.  The part of the token after the package marker must
not have the syntax of a number.

If there is a single package marker not at the beginning or end of the
token, then it divides the token into two parts.  The first part
specifies a package; the second part is the name of an external symbol
available in that package.  Neither of the two parts may have the syntax
of a number.

If there is are two adjacent package markers not at the beginning or end of the
token, then they divide the token into two parts.  The first part
specifies a package; the second part is the name of a symbol within
that package (possibly an internal symbol).
Neither of the two parts may have the syntax of a number.

If a symbol token contains no package markers, then the entire token
is the name of the symbol.  The symbol is looked up in
the default package; see @Varref[package].

All other patterns of package markers,
including the cases where there are more than two
package markers or where a package marker appears at the end of the token,
presently do not mean anything in @clisp; see chapter @ref[XPACK].
It is therefore currently an error to use such patterns in a @clisp program.
The valid patterns for tokens may be summarized as follows:
@Begin[Format, Group]
@tabdivide[3]
@=@i[nnnnn]@\a number
@=@i[xxxxx]@\a symbol in the current package
@=@f[:@i[xxxxx]]@\a symbol in the keyword package
@=@f[@i[ppppp]:@i[xxxxx]]@\an external symbol in the @i[ppppp] package
@=@f[@i[ppppp]::@i[xxxxx]]@\a (possibly internal) symbol in the @i[ppppp] package
@End[Format]
where @i[nnnnn] has the syntax of a number, and @i[xxxxx] and @i[ppppp] do
not have the syntax of a number.

@Begin[FullPageTable]
@Mline[]
@Caption[Standard Constituent Character Attributes]
@Tag[Standard-Readtable-Attributes-Table]
@Begin[Format]
@Tabset[+0.4 in, +2.1 in, +0.8 in]
@f[!]@\@i[alphabetic]@\<backspace>@\@i[illegal]
@f["]@\@i[alphabetic] *@\<tab>@\@i[illegal] *
@f[#]@\@i[alphabetic] *@\<newline>@\@i[illegal] *
@f[$]@\@i[alphabetic]@\<linefeed>@\@i[illegal] *
@f[%]@\@i[alphabetic]@\<page>@\@i[illegal]
@f[&]@\@i[alphabetic]@\<return>@\@i[illegal] *
@f[']@\@i[alphabetic] *@\<space>@\@i[illegal] *
@f[(]@\@i[alphabetic] *@\@f[+]@\@i[alphabetic], @i[plus sign]
@f[)]@\@i[alphabetic] *@\@f[-]@\@i[alphabetic], @i[minus sign]
@f[*]@\@i[alphabetic]@\@f[.]@\@i[alphabetic], @i[dot], @i[decimal point]
@f[,]@\@i[alphabetic] *@\@f[/]@\@i[alphabetic], @i[ratio marker]
@f[0]@\@i[alphadigit]@\@f[A], @f[a]@\@i[alphadigit]
@f[1]@\@i[alphadigit]@\@f[B], @f[b]@\@i[alphadigit]
@f[2]@\@i[alphadigit]@\@f[C], @f[c]@\@i[alphadigit]
@f[3]@\@i[alphadigit]@\@f[D], @f[d]@\@i[alphadigit], @i[double-float exponent marker]
@f[4]@\@i[alphadigit]@\@f[E], @f[e]@\@i[alphadigit], @i[float exponent marker]
@f[5]@\@i[alphadigit]@\@f[F], @f[f]@\@i[alphadigit], @i[single-float exponent marker]
@f[6]@\@i[alphadigit]@\@f[G], @f[g]@\@i[alphadigit]
@f[7]@\@i[alphadigit]@\@f[H], @f[h]@\@i[alphadigit]
@f[8]@\@i[alphadigit]@\@f[I], @f[i]@\@i[alphadigit]
@f[9]@\@i[alphadigit]@\@f[J], @f[j]@\@i[alphadigit]
@f[:]@\@i[package marker]@\@f[K], @f[k]@\@i[alphadigit]
@f[;]@\@i[alphabetic] *@\@f[L], @f[l]@\@i[alphadigit], @i[long-float exponent marker]
@f[<]@\@i[alphabetic]@\@f[M], @f[m]@\@i[alphadigit]
@f[=]@\@i[alphabetic]@\@f[N], @f[n]@\@i[alphadigit]
@f[>]@\@i[alphabetic]@\@f[O], @f[o]@\@i[alphadigit]
@f[?]@\@i[alphabetic]@\@f[P], @f[p]@\@i[alphadigit]
@f[@@]@\@i[alphabetic]@\@f[Q], @f[q]@\@i[alphadigit]
@f{[⎇@\@i[alphabetic]@\@f[R], @f[r]@\@i[alphadigit]
@f[\]@\@i[alphabetic] *@\@f[S], @f[s]@\@i[alphadigit], @i[short-float exponent marker]
@f{]⎇@\@i[alphabetic]@\@f[T], @f[t]@\@i[alphadigit]
@f[↑]@\@i[alphabetic]@\@f[U], @f[u]@\@i[alphadigit]
@f[@underscore]@\@i[alphabetic]@\@f[V], @f[v]@\@i[alphadigit]
@f[@bq]@\@i[alphabetic] *@\@f[W], @f[w]@\@i[alphadigit]
@f[{]@\@i[alphabetic]@\@f[X], @f[x]@\@i[alphadigit]
@f[|]@\@i[alphabetic] *@\@f[Y], @f[y]@\@i[alphadigit]
@f[⎇]@\@i[alphabetic]@\@f[Z], @f[z]@\@i[alphadigit]
@f[@tilde]@\@i[alphabetic]@\<rubout>@\@i[illegal]
@End[Format]
@Begin[Text, font smallbodyfont, indent 0]
The interpretations in this table apply only to characters whose
syntactic type is @i[constituent].  Entries marked
with an asterisk are normally shadowed because the indicated characters
are of syntactic type
@i[whitespace], @i[macro], @i[single escape], or @i[multiple escape].
Characters with the @i[alphadigit] attribute are interpreted as having
the digit or alphabetic attribute according to whether or not the
character is a valid digit in the radix specified by @Varref[read-base].
Characters with the @i[illegal] attribute cannot ever appear in
a token except under the control of an escape character.
@End[Text]
@blankspace[.5]
@Mline[]
@End[FullPageTable]

@Defvar[Var {read-base⎇]
The value of @var[read-base] controls the interpretation of tokens
by @Funref[read] as being integers or ratios.  Its value is the radix
in which integers and ratios are to be read; the value may be any integer
from @f[2] to @f[36] (inclusive) and is normally @f[10] (decimal radix).
Its value affects only the reading of integers and ratios.
In particular, floating-point numbers are always read in decimal radix.
The value of @var[read-base] does not affect the radix for rational numbers
whose radix is explicitly indicated by
@f[#O], @f[#X], @f[#B], or @f[#@i[n]R] syntax
or by a trailing decimal point.

Care should be taken when setting @var[read-base] to a value larger
than @f[10], because tokens that would normally be interpreted as
symbols may be interpreted as numbers instead.  For example,
with @var[read-base] set to @f[16] (hexadecimal radix), variables
with names such as @f[a], @f[b], @f[f], @f[bad], and @f[face]
will be treated by the reader as numbers (with decimal values
10, 11, 12, 2989, and 64206, respectively).  The ability to alter
the input radix is provided in @clisp primarily for the purpose of
reading data files in special formats, rather than for the purpose of altering
the default radix in which to read programs.  The user is strongly
encouraged to use @f[#O], @f[#X], @f[#B], or @f[#@i[n]R] syntax when
notating non-decimal constants in programs.

@Incompatibility{This variable corresponds to the variable
called @f[ibase] in @maclisp and to the function called @f[radix]
in @interlisp.⎇
@Enddefvar

@Defvar[Var {read-suppress⎇]
When the value of @var[read-suppress] is @nil, the @xlisp reader
operates normally.  When it is not @nil, then most of the interesting
operations of the reader are suppressed; input characters are parsed,
but much of what is read is not interpreted.

The primary purpose of @var[read-suppress] is to support the operation of
the read-time conditional constructs @f[#+] and @f[#-] (see section
@ref[SHARP-SIGN-MACRO-CHARACTER-SECTION]).  It is important for these
constructs to be able to skip over the printed representation of a @xlisp
expression despite the possibility that the syntax of the skipped
expression may not be entirely legal for the current implementation; this
is because a primary application of @f[#+] and @f[#-] is to allow the
same program to be shared among several @xlisp implementations despite
small incompatibilities of syntax.)

A non-@nil value of @var[read-suppress] has the following specific
effects on the @clisp reader:
@Begin[Itemize]
All extended tokens are completely uninterpreted.  It matters not
whether the token looks like a number, much less like a valid number;
the pattern of package markers also does not matter.  An extended token
is simply discarded and treated as if it were @nil; that is, reading
an extended token when @var[read-suppress] is non-@nil simply returns @nil.
(One consequence of this is that the error concerning improper
dotted-list syntax will not be signalled.)

Any standard
@f[#] macro-character construction that requires, permits, or disallows
an infix numerical argument, such as @f[#@i[n]R], will not enforce
any constraint on the presence, absence, or value of such an argument.

The @f[#\] construction always produces the value @nil.
It will not signal an error even if an unknown character name is seen.

Each of the @f[#B], @f[#O], @f[#X], and @f[#R]
constructions always scans over a following token and produces the value @nil.
It will not signal an error even if the token does not have the syntax
of a rational number.

The @f[#*] construction always scans over a following token and
produces the value @nil.
It will not signal an error even if the token does not consist solely
of the characters @f[0] and @f[1].

Each of the @f[#.] and @f[#,] constructions reads the following
form (in suppressed mode, of course) but does not evaluate it.
The form is discarded and @nil is produced.

Each of the @f[#A], @f[#S], and @f[#:]
constructions reads the following
form (in suppressed mode, of course) but does not interpret it in any way;
it need not even be a list in the case of @f[#S], or a symbol
in the case of @f[#:].  The form is discarded and @nil is produced.

The @f[#=] construction is totally ignored.  It does not read
a following form.  It produces no object, but is treated as whitespace.

The @f[##] construction always produces @nil.
@End[Itemize]
Note that, no matter what the value of @var[read-suppress],
parentheses still continue to delimit (and construct) lists;
the @f[#(] construction continues to delimit vectors;
and comments, strings, and the quote and backquote constructions continue to be
interpreted properly.  Furthermore, such situations as
@f[')],
@f[#<], @f[#)], and @f[#<space>] continue to signal errors.

In some cases, it may be appropriate for a user-written macro-character
definition to check the value of @var[read-suppress] and avoid certain
computations or side effects if its value is not @nil.
@Enddefvar

@Subsection[Macro Characters]
@Label[MACRO-CHARACTERS-SECTION]
@Index[parsing]
@Index[macro character]
If the reader encounters a macro
character, then the function associated with that macro character is
invoked and may produce an object to be returned.  This function may read
following characters in the stream in whatever syntax it likes (it may
even call @f[read] recursively) and return the object represented by
that syntax.  Macro characters may or may not be recognized, of course,
when read as part of other special syntaxes (such as for strings).

The reader is therefore organized into two parts: the basic dispatch loop,
which also distinguishes symbols and numbers, and the collection
of macro characters.  Any character can be reprogrammed as a macro character;
this is a means by which the reader can be extended.
The macro characters normally defined are as follows:
@Begin[Description, Leftmargin +.3 in, Indent -.3 in]
@Begin[Multiple, Spread 0.3]
@f[(]@\The left-parenthesis character initiates reading of a pair or list.
@Index{@f[( ]macro character⎇
@Index[list syntax]
The function @Funref[read] is called recursively to read successive objects
until a right parenthesis is found to be next in the input stream.
A list of the objects read is returned.  Thus
@Lisp
(a b c)
@Endlisp
is read as a list of three objects (the symbols @f[a], @f[b], and @f[c]).
The right parenthesis need not immediately follow the printed representation of
the last object; whitespace
characters and comments may precede it.
This can be useful for putting one object
on each line and making it easy to add new objects:
@Lisp
(defun traffic-light (color)
  (case color
    (green)
    (red (stop))
    (amber (accelerate))	;@r[Insert more colors after this line.]
    ))
@Endlisp

It may be that @i[no] objects precede the right parenthesis, as in @f[()]
or @f[( )]; this reads as a list of zero objects (the empty list).

If a token that is just a dot,
not preceded by an escape character,
is read after some object
then exactly one more object must follow the dot,
possibly followed by whitespace,
followed by the right parenthesis:
@Lisp
(a b c . d)
@Endlisp
This means that the @i[cdr] of the last pair in the list is not @nil,
but rather the object whose representation followed the dot.
The above example might have been the result of evaluating
@Lisp
(cons 'a (cons 'b (cons 'c 'd))) @EV (a b c . d)
@Endlisp
Similarly, we have
@Lisp
(cons 'znets 'wolq-zorbitan) @EV (znets . wolq-zorbitan)
@Endlisp
It is permissible for the object following the dot to be a list:
@Lisp
(a b c d . (e f . (g)))  @r[is the same as]  (a b c d e f g)
@Endlisp
but this is a non-standard form that @f[print] will never produce.
@End[Multiple]

@f[)]@\The right-parenthesis character is part of various constructs
(such as the syntax for lists) using the left-parenthesis character and
is invalid except when used in such a construct.
@Index{@f[) ]macro character⎇

@f[']@\The single-quote (accent acute) character provides
an abbreviation to make it easier to put constants in programs.
@Index{@f[' ]macro character⎇
@Index[quote character]
@f['@i[foo]] reads the same as @f[(quote @i[foo])]: a list of the symbol
@f[quote] and @i[foo].

@Begin[Multiple, Spread 0.3]
@f[;]@\Semicolon is used to write comments.
@Index{@f[; ]macro character⎇
@Index[comments]
The semicolon and all characters
up to and including the next newline are ignored.
Thus a comment can be put at
the end of any line without affecting the reader.
(A comment will terminate a token, but a newline would terminate the
token anyway.)
For example:
@lisp
;;;; COMMENT-EXAMPLE function.
;;; This function is useless except to demonstrate comments.
;;; (Actually, this example is much too cluttered with them.)
;;; Notice that there are several kinds of comments.

(defun comment-example (x y)	;X is anything; Y is an a-list.
  (cond ((listp x) x)		;If X is a list, use that.
	;; X is now not a list.  There are two other cases.
	((symbolp x)
	 ;; Look up a symbol in the a-list.
	 (cdr (assoc x y)))	;Remember, (cdr @false) is @false.
	;; Do this when all else fails:
	(t (cons x		;Add x to a default list.
		 '((lisp t)	;LISP is okay.
		   (fortran @false)	;FORTRAN is not.
		   (pl/i -500)	;Note that you can put comments in
		   (ada .001)	; "data" as well as in "programs".
		   ;; COBOL??
		   (teco -1.0e9))))))
@Endlisp
This example illustrates a few conventions for comments in common use.
Comments may begin with one to four semicolons.
@Begin[Itemize]
Single-semicolon comments are all aligned to the same column at
the right; usually each comments about only the line it is on.
Occasionally two or three contain a single sentence together; this is
indicated by indenting all but the first by a space (after the
semicolon).

Double-semicolon comments are aligned to the level of indentation
of the code.  A space follows the two semicolons.
Usually each describes the state of the program at that point
or describes the section that follows.

Triple-semicolon comments are aligned to the left margin.
Usually they are not used within function definitions but precede
them in large blocks.

Quadruple-semicolon comments are interpreted as subheadings.
@End[Itemize]
@Incompatibility{These conventions arose among users of @maclisp
and have been found to be very useful.
The conventions are conveniently exploited by certain software tools,
such as the @c[emacs] editor and the
@c[atsign] listing program developed at @c[MIT].⎇
@End[Multiple]

@f["]@\The double quote character begins the printed representation
of a string.
@Index{@f[" ]macro character⎇
@Index[string syntax]
Characters are read from the input stream and accumulated until
another double quote is encountered.
An exception to this occurs if a @i[single escape] character
is seen; the escape character is discarded,
the next character is accumulated, and accumulation
continues.  When a matching double quote is seen, all the accumulated
characters up to but not including the matching double quote are
made into a simple string and returned.

@Begin[Multiple, Spread 0.3]
@f[@bq]@\The backquote (accent grave) character
makes it easier to write programs to construct complex data structures by
using a template.
@label[BACKQUOTE]
@Index{@f[@bq ]macro character⎇@;
As an example, writing
@Lisp
@bq@;(cond ((numberp ,x) ,@@y) (t (print ,x) ,@@y))
@Endlisp
is roughly equivalent to writing
@Lisp
(list 'cond 
      (cons (list 'numberp x) y) 
      (list* 't (list 'print x) y))
@Endlisp
The general idea is that the backquote is followed by a template,
a picture of a data structure to be built.  This template is copied,
except that within the template commas can appear.  Where a comma
occurs, the form following the comma is to be evaluated to produce an object to
be inserted at that point.  Assume @f[b] has the value 3, for example, then
evaluating the form denoted by @f[@bq@;(a b ,b ,(+ b 1) b)] produces
the result @f[(a b 3 4 b)].

If a comma is immediately followed by an at-sign (@f[@@]), then the
form following the at-sign is evaluated to produce a @i[list] of objects.
These objects are then ``spliced'' into place in the template.  For
example, if @f[x] has the value @f[(a b c)], then
@Lisp
@bq@;(x ,x ,@@x foo ,(cadr x) bar ,(cdr x) baz ,@@(cdr x))
   @EV (x (a b c) a b c foo b bar (b c) baz b c)
@Endlisp

The backquote syntax can be summarized formally as follows.
For each of several situations in which backquote can be used,
a possible interpretation of that situation as an equivalent form
is given.  Note that the form is equivalent only
in the sense that when it is evaluated it will calculate the
correct result.
An implementation is quite free to interpret backquote in any way
such that a backquoted form, when evaluated, will produce a result
@f[equal] to that produced by the interpretation shown here.
@Begin[Itemize]
@f[@bq@i[basic]] is the same as @f['@i[basic]],
that is, @f[(quote @i[basic])], for any form @i[basic] that is not a
list or a general vector.

@f[@bq,@i[form]] is the same as @i[form], for any @i[form], provided
that the representation of @i[form] does not begin with ``@f[@@]''
or ``@f[.]''.  (A similar caveat holds for all occurrences of a form
after a comma.)

@f[@bq,@@@i[form]] is an error.

@Begin[Multiple, Spread 0.3]
@f[@bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn] . @i[atom])] may be interpreted to mean
@lisp
(append @r{@lbracket⎇@i[x1]@r{@rbracket⎇ @r{@lbracket⎇@i[x2]@r{@rbracket⎇ @r{@lbracket⎇@i[x3]@r{@rbracket⎇ ... @r{@lbracket⎇@i[xn]@r{@rbracket⎇ (quote @i[atom]))
@endlisp
where the brackets are used to indicate
a transformation of an @i[xj] as follows:
@Begin[Itemize]
@r{@lbracket⎇@i[form]@r{@rbracket⎇ is interpreted as @f[(list @bq@i[form])], which
contains a backquoted form that must then be further interpreted.

@r{@lbracket⎇@f[,@i[form]]@r{@rbracket⎇ is interpreted as @f[(list @i[form])].

@r{@lbracket⎇@f[,@@@i[form]]@r{@rbracket⎇ is interpreted simply as @i[form].
@End[Itemize]
@End[Multiple]

@f[@bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn])] may be interpreted to mean
the same as the backquoted form
@f[@bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn] . @nil)],
thereby reducing it to the previous case.

@Begin[Multiple]
@f[@bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn] . ,@i[form])] may be interpreted to mean
@lisp
(append @r{@lbracket⎇@i[x1]@r{@rbracket⎇ @r{@lbracket⎇@i[x2]@r{@rbracket⎇ @r{@lbracket⎇@i[x3]@r{@rbracket⎇ ... @r{@lbracket⎇@i[xn]@r{@rbracket⎇ @i[form])
@endlisp
where the brackets indicate a transformation of an @i[xj] as described above.
@End[Multiple]

@f[@bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn] . ,@@@i[form])] is an error.

@f[@bq#(@i[x1] @i[x2] @i[x3] ... @i[xn])] may be interpreted to mean
@f[(apply #'vector @bq@;(@i[x1] @i[x2] @i[x3] ... @i[xn]))].
@End[Itemize]
No other uses of comma are permitted; in particular, it may not appear within
the @f[#A] or @f[#S] syntax.

Anywhere ``@f[,@@]'' may be used, the syntax ``@f[,.]'' may be used instead
to indicate that it is permissible to destroy the list produced by the form
following the ``@f[,.]''; this may permit more efficient code, using
@Funref[nconc] instead of @Funref[append], for example.

If the backquote syntax is nested, the innermost backquoted form
should be expanded first.  This means that if several commas occur
in a row, the leftmost one belongs to the innermost backquote.

Once again, it is emphasized that an implementation is free to interpret
a backquoted form as any form that, when evaluated, will produce a result
that is @f[equal] to the result implied by the above definition.
In particular, no guarantees are made as to whether the constructed
copy of the template will or will not share list structure with the
template itself.  As an example, the above definition implies that
@lisp
@bq@;((,a b) ,c ,@@d)
@endlisp
will be interpreted as if it were
@Lisp
(append (list (append (list a) (list 'b) '@nil)) (list c) d '@nil)
@Endlisp
but it could also be legitimately interpreted to mean any of the following:
@Lisp
(append (list (append (list a) (list 'b))) (list c) d)
(append (list (append (list a) '(b))) (list c) d)
(append (list (cons a '(b))) (list c) d)
(list* (cons a '(b)) c d)
(list* (cons a (list 'b)) c d)
(list* (cons a '(b)) c (copy-list d))
@Endlisp
(There is no good reason why @f[copy-list] should be performed, but
it is not prohibited.)
@End[Multiple]

@f[,]@\The comma character is part of the backquote syntax
and is invalid if used other than inside the body of a backquote
construction as described above.
@Index{@f[, ]macro character⎇

@Begin[Multiple]
@f[#]@\This is a @i[dispatching] macro character.
It reads an optional digit string and then one more character,
and uses that character to select a function to run as a macro-character
function.

The @f[#] character also happens to be a non-terminating
macro character.  This is completely independent of the fact that
it is a dispatching macro character; it is a coincidence that
the only standard dispatching macro character in @clisp is
also the only standard non-terminating macro character.

See the next section for predefined @f[#] macro-character constructions.
@End[Multiple]

@End[Description]

@Subsection[Standard Dispatching Macro Character Syntax]
@label[SHARP-SIGN-MACRO-CHARACTER-SECTION]
@Index{@f[# ]macro character⎇

The standard syntax includes forms introduced by the @f[#] character.
These take the general form of a @f[#],
a second character that identifies the syntax,
and following arguments in some form.
If the second character is a letter, then case is not important;
@f[#O] and @f[#o] are considered to be equivalent, for example.

Certain @f[#] forms allow an unsigned decimal number to appear
between the @f[#] and the second character; some other
forms even require it.  Those forms that do not explicitly permit
such a number to appear forbid it.

@Begin[FullPageTable]
@Mline[]
@Caption[Standard # Macro Character Syntax]
@Tag[Standard-Sharp-Macro-Definitions-Table]
@Begin[Format]
@Tabset[+0.9 in, +2.1 in, +0.9 in]
@f[#!]@\@i[undefined] *@\@f[#]<backspace>@\@i[signals error]
@f[#"]@\@i[undefined]@\@f[#]<tab>@\@i[signals error]
@f[##]@\@i[reference to @f[#=] label]@\@f[#]<newline>@\@i[signals error]
@f[#$]@\@i[undefined]@\@f[#]<linefeed>@\@i[signals error]
@f[#%]@\@i[undefined]@\@f[#]<page>@\@i[signals error]
@f[#&]@\@i[undefined]@\@f[#]<return>@\@i[signals error]
@f[#']@\@i[@f[function] abbreviation]@\@f[#]<space>@\@i[signals error]
@f[#(]@\@i[simple vector]@\@f[#+]@\@i[read-time conditional]
@f[#)]@\@i[signals error]@\@f[#-]@\@i[read-time conditional]
@f[#*]@\@i[bit-vector]@\@f[#.]@\@i[read-time evaluation]
@f[#,]@\@i[load-time evaluation]@\@f[#/]@\@i[undefined]
@f[#0]@\@i[used for infix arguments]@\@f[#A], @f[#a]@\@i[array]
@f[#1]@\@i[used for infix arguments]@\@f[#B], @f[#b]@\@i[binary rational]
@f[#2]@\@i[used for infix arguments]@\@f[#C], @f[#c]@\@i[complex number]
@f[#3]@\@i[used for infix arguments]@\@f[#D], @f[#d]@\@i[undefined]
@f[#4]@\@i[used for infix arguments]@\@f[#E], @f[#e]@\@i[undefined]
@f[#5]@\@i[used for infix arguments]@\@f[#F], @f[#f]@\@i[undefined]
@f[#6]@\@i[used for infix arguments]@\@f[#G], @f[#g]@\@i[undefined]
@f[#7]@\@i[used for infix arguments]@\@f[#H], @f[#h]@\@i[undefined]
@f[#8]@\@i[used for infix arguments]@\@f[#I], @f[#i]@\@i[undefined]
@f[#9]@\@i[used for infix arguments]@\@f[#J], @f[#j]@\@i[undefined]
@f[#:]@\@i[uninterned symbol]@\@f[#K], @f[#k]@\@i[undefined]
@f[#;]@\@i[undefined]@\@f[#L], @f[#l]@\@i[undefined]
@f[#<]@\@i[signals error]@\@f[#M], @f[#m]@\@i[undefined]
@f[#=]@\@i[label following object]@\@f[#N], @f[#n]@\@i[undefined]
@f[#>]@\@i[undefined]@\@f[#O], @f[#o]@\@i[octal rational]
@f[#?]@\@i[undefined] *@\@f[#P], @f[#p]@\@i[undefined]
@f[#@@]@\@i[undefined]@\@f[#Q], @f[#q]@\@i[undefined]
@f{[⎇@\@i[undefined] *@\@f[#R], @f[#r]@\@i[radix-n rational]
@f[#\]@\@i[character object]@\@f[#S], @f[#s]@\@i[structure]
@f{]⎇@\@i[undefined] *@\@f[#T], @f[#t]@\@i[undefined]
@f[#↑]@\@i[undefined]@\@f[#U], @f[#u]@\@i[undefined]
@f[#@underscore]@\@i[undefined]@\@f[#V], @f[#v]@\@i[undefined]
@f[#@bq]@\@i[undefined]@\@f[#W], @f[#w]@\@i[undefined]
@f[#{]@\@i[undefined] *@\@f[#X], @f[#x]@\@i[hexadecimal rational]
@f[#|]@\@i[balanced comment]@\@f[#Y], @f[#y]@\@i[undefined]
@f[#⎇]@\@i[undefined] *@\@f[#Z], @f[#z]@\@i[undefined]
@f[#@tilde]@\@i[undefined]@\@f[#]<rubout>@\@i[undefined]
@End[Format]
@Begin[Text, font smallbodyfont, indent 0]
* The combinations marked by an asterisk are explicitly reserved to the user
and will never be defined by @clisp. 
@End[Text]
@Mline[]
@End[FullPageTable]

The currently-defined @f[#] constructs are described below
and summarized in Table @Ref[Standard-Sharp-Macro-Definitions-Table];
more are likely to be added in the future.  However, the constructs
@f[#!], @f[#?], @f{#@lbracket@;⎇, @f{#@rbracket@;⎇,
@f[#@lbrace@;], and @f[#@rbrace@;]
are explicitly reserved for the user and will never be defined by the
@clisp standard.
@Begin[Description, Leftmargin +.5 in, Indent -.5 in]
@Begin[Multiple, Spread 0.3]
@f[#\]@\@}
@f[#\@i[x]] reads in as a character object that represents the
character @i[x].  Also, @f[#\@i[name]] reads in as the character object
whose name is @i[name].
@Index[character syntax]
Note that the backslash @f[\] allows this
construct to be parsed easily by @c[emacs]-like editors.

In the single-character case, the character @i[x] must be followed
by a non-constituent character, lest a @i[name] appear to follow the
@f[#\].  A good model of what happens is that after @f[#\] is read,
the reader backs up over the @f[\] and then reads an extended token,
treating the initial @f[\] as an escape character (whether it really
is or not in the current readtable).

Uppercase and lowercase letters are distinguished after @f[#\];
@f[#\A] and @f[#\a] denote different character objects.  Any
character works after @f[#\], even those that are normally special to
@f[read], such as parentheses.  Non-printing characters may be used
after @f[#\], although for them names are generally preferred.

@f[#\@i[name]] reads in as a character object whose name is @i[name]
(actually, whose name is @f[(string-upcase @i[name])];
therefore the syntax is case-insensitive).
The @i[name] should have the syntax of a symbol.
The following names are standard across all implementations:
@Begin[DenseDescription]
@f[newline]@\The character that represents the division between lines

@f[space]@\The space or blank character
@End[DenseDescription]
The following names are semi-standard; if an implementation supports
them, they should be used for the described characters and no others.
@Begin[DenseDescription]
@f[rubout]@\The rubout or delete character

@f[page]@\The form-feed or page-separator character

@f[tab]@\The tabulate character

@f[backspace]@\The backspace character

@f[return]@\The carriage return character

@f[linefeed]@\The line-feed character
@End[DenseDescription]
In some implementations, one or more of these characters might be
a synonym for a standard character; for example, @f[#\Linefeed]
might be the same as @f[#\Newline].

When the @xlisp printer types out the name of a special character, it uses the
same table as the @f[#\] reader; therefore any character name you see typed out
is acceptable as input (in that implementation).  Standard names are always
preferred over non-standard names for printing.

The following convention is used in implementations that support
non-zero bits attributes for character objects.
If a name after @f[#\] is longer than one character and has a hyphen in it,
then it may be split into the two parts preceding
and following the first hyphen; the first part (actually, @f[string-upcase]
of the first part)
may then be interpreted as
the name or initial of a bit, and the second part as the name of the character
(which may in turn contain a hyphen and be subject to further splitting).
For example:
@lisp
#\Control-Space			#\Control-Meta-Tab
#\C-M-Return			#\H-S-M-C-Rubout
@Endlisp
If the character name consists of a single character, then that character
is used.  Another @f[\] may be necessary to quote the character.
@Lisp
#\Control-%			#\Control-Meta-\"
#\Control-\a			#\Meta->
@Endlisp

If an unsigned decimal integer appears between the @f[#] and @f[\],
it is interpreted as a font number, to become the font attribute
of the character object (see @f[char-font]).
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#']@\@}
@f[#'@i[foo]] is an abbreviation for @f[(function @i[foo])].
@i[foo] may be the printed representation of any @xlisp object.
This abbreviation may be remembered by analogy with the @f[']
macro-character, since the @f[function] and @f[quote] special forms are
similar in form.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#(]@\@}
A series of representations of objects enclosed by @f[#(] and @f[)]
is read as a simple vector of those objects.  This is analogous to
the notation for lists.

If an unsigned decimal integer appears between the @f[#] and @f[(],
it specifies explicitly the length of the vector.  In that case,
it is an error if too many objects are specified before the closing @f[)],
and if too few are specified, the last object
(it is an error if there are none in this case)
is used to fill all
remaining elements of the vector.
For example,
@lisp
#(a b c c c c)
#6(a b c c c c)
#6(a b c)
#6(a b c c)
@Endlisp
all mean the same thing: a vector of length 6 with elements @f[a], @f[b],
and four instances of @f[c].  
The notation @f[#()] denotes an empty vector, as does @f[#0()]
(which is legitimate because it is not the case that too few elements
are specified).
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#*]@\@}
A series of binary digits (@f[0] and @f[1]) preceded by @f[#*] is
read as a simple bit-vector containing those bits, the leftmost bit
in the series being bit 0 of the bit-vector.

If an unsigned decimal integer appears between the @f[#] and @f[*],
it specifies explicitly the length of the vector.  In that case,
it is an error if too many bits are specified,
and if too few are specified the last one
(it is an error if there are none in this case)
is used to fill all remaining elements of the bit-vector.
For example,
@lisp
#*101111
#6*101111
#6*101
#6*1011
@Endlisp
all mean the same thing: a vector of length 6 with elements @f[1], @f[0],
@f[1], @f[1], @f[1], and @f[1].
The notation @f[#*] denotes an empty bit-vector, as does @f[#0*]
(which is legitimate because it is not the case that too few elements
are specified).
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#:]@\@}
@f[#:@i[foo]] requires @i[foo] to have the syntax of an unqualified
symbol name (no embedded colons).  It denotes an @i[uninterned] symbol
whose name is @i[foo].  Every time this syntax is encountered, a different
uninterned symbol is created.  If it is necessary to refer to the
same uninterned symbol more than once in the same expression,
the @f[#=] syntax may be useful.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#.]@\@}
@f[#.@i[foo]] is read as the object resulting from the evaluation
of the @xlisp object represented by @i[foo],
which may be the printed representation of any @xlisp object.
The evaluation is done during the @f[read] process, when the @f[#.]
construct is encountered.
The @f[#.] syntax therefore performs a read-time evaluation of @i[foo].
By contrast, @f[#,] (see below) performs a load-time evaluation.

Both @f[#.] and @f[#,] allow you to include, in an expression
being read, an object that does not have a convenient printed
representation; instead of writing a representation for the object,
you write an expression that will @i[compute] the object.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#,]@\@}
@f[#,@i[foo]] is read as the object resulting from the evaluation
of the @xlisp object represented by @i[foo],
which may be the printed representation of any @xlisp object.
The evaluation is done during the @f[read] process,
unless the compiler is doing the reading, in which case it is arranged
that @i[foo] will be evaluated when the file of compiled code is loaded.
The @f[#,] syntax therefore performs a load-time evaluation of @i[foo].
By contrast, @f[#.] (see above) performs a read-time evaluation.
In a sense, @f[#,] is like specifying @f[(eval load)] to
@Specref[eval-when], whereas @f[#.] is more like specifying @f[(eval compile)].
It makes no difference when loading interpreted code; when code
is to be compiled, however, @f[#.] specifies compile-time evaluation and
@f[#,] specifies load-time evaluation.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#B]@\@}
@f[#b@i[rational]] reads @i[rational] in binary (radix 2).
For example, @f[#B1101] @EQ @f[13], and @f[#b101/11] @EQ @f[5/3].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#O]@\@}
@f[#o@i[rational]] reads @i[rational] in octal (radix 8).
For example, @f[#o37/15] @EQ @f[31/13], and @f[#o777] @EQ @f[511].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#X]@\@}
@f[#x@i[rational]] reads @i[rational] in hexadecimal (radix 16).
The digits above @f[9] are the letters @f[A] through @f[F] (the lowercase
letters @f[a] through @f[f] are also acceptable).  For example,
@f[#xF00] @EQ @f[3840].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#@i[n]R]@\@}
@f[#@i[radix]r@i[rational]] reads @i[rational] in radix @i[radix].
@i[radix] must consist of only digits, and
it is read in decimal; its value must be between 2 and 36 (inclusive).

For example, @f[#3r102] is another way of writing @f[11], and @f[#11R32]
is another way of writing @f[35].  For radices larger than 10, letters of
the alphabet are used in order for the digits after @f[9].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#@i[n]A]@\@}
The syntax @f[#@i[n]A@i[object]] constructs an @i[n]-dimensional array,
using @i[object] as the value of the @Kwd[initial-contents] argument
to @Funref[make-array].

The value of @i[n] makes a difference.
For example, @f[#2A((0 1 5) (foo 2 (hot dog)))] represents a 2-by-3 matrix:
@lisp
@tabset[+1in]
@\0       1       5
@\foo     2       (hot dog)
@endlisp
In contrast, @f[#1A((0 1 5) (foo 2 (hot dog)))] represents a length-2
array whose elements are lists:
@lisp
@tabset[+1in]
@\(0 1 5)    (foo 2 (hot dog))
@endlisp
Furthermore, @f[#0A((0 1 5) (foo 2 (hot dog)))] represents a zero-dimensional
array whose sole element is a list:
@lisp
@tabset[+1in]
@\((0 1 5) (foo 2 (hot dog)))
@endlisp
Similarly, @f[#0Afoo] (or, more readably, @f[#0A foo]) represents
a zero-dimensional array whose sole element is the symbol @f[foo].
The expression @f[#1Afoo] would not be legal because @f[foo] is
not a sequence.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#S]@\@}
The syntax @f[#s(@i[name] @i[slot1] @i[value1] @i[slot2] @i[value2] ...)]
denotes a structure.  This is legal only if @i[name] is the name
of a structure already defined by @Macref[defstruct] and if the
structure has a standard constructor macro, which it normally will.
Let @i[cm] stand for the name of this constructor macro;
then this syntax is equivalent to
@Lisp
#.(@i[cm] @i[keyword1] '@i[value1] @i[keyword2] '@i[value2] ...)
@Endlisp
where each @i[keywordj] is the result of computing
@lisp
(intern (string @i[slotj]) 'keyword)
@endlisp
(This computation is made so that one need not write a colon in
front of every slot name.)
The net effect is that the constructor macro is called
with the specified slots
having the specified values (note that one does not write quote marks
in the @f[#S] syntax).  Whatever object the constructor macro returns
is returned by the @f[#S] syntax.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#@i[n]=]@\@}
The syntax @f[#@i[n]=@i[object]] reads as whatever @xlisp object
has @i[object] as its printed representation.  However, that object
is labelled by @i[n], a required unsigned decimal integer, for
possible reference by the syntax @f[#@i[n]#] (below).
The scope of the label is the expression being read by the outermost
call to @f[read].  Within this expression
the same label may not appear twice.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#@i[n]#]@\@}
The syntax @f[#@i[n]#], where @i[n] is a required unsigned decimal integer,
serves as a reference to some object labelled by @f[#@i[n]=];
that is, @f[#@i[n]#] represents a pointer to the same identical
(@f[eq]) object labelled by @f[#@i[n]=].
This permits notation of structures with shared or circular substructure.
For example, a structure created in the variable @f[y] by this code:
@Lisp
(setq x (list 'p 'q))
(setq y (list (list 'a 'b) x 'foo x))
(rplacd (last y) (cdr y))
@Endlisp
could be represented in this way:
@Lisp
((a b) . #1=(#2=(p q) foo #2# . #1#))
@Endlisp
Without this notation, but with @Varref[print-length] set to @f[10],
the structure would print in this way:
@Lisp
((a b) (p q) foo (p q) (p q) foo (p q) (p q) foo (p q) ...)
@Endlisp
A reference @f[#@i[n]#] may only occur after a label @f[#@i[n]=];
forward references are not permitted.  In addition, the reference
may not appear as the labelled object itself (that is,
one may not write @f[#@i[n]= #@i[n]#]), because the object
labelled by @f[#@i[n]=] is not well defined in this case.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#+]@\@}
@Index2[P {conditional⎇, S {during @f[read]⎇]
@label[READ-TIME-CONDITIONAL]
The @f[#+] syntax provides a read-time conditionalization facility;
the syntax is
@lisp
#+@i[feature] @i[form]
@endlisp
If @i[feature] is ``true,'' then this syntax represents a @xlisp object
whose printed representation is @i[form].  If @i[feature] is ``false,''
then this syntax is effectively whitespace; it is as if it did not appear.

The @i[feature] should be the printed representation of a symbol or list.
If @i[feature] is a symbol, then 
it is true if and only if it is a member of the list that is the value of
the global variable @Varref[features].
@Incompatibility{@Maclisp uses the @f[status] special form for
this purpose, and @lmlisp duplicates @f[status] essentially only
for the sake of @f[(status features)].  The use of a variable allows
one to bind the features list, when compiling. for example.⎇
Otherwise,
@i[feature] should be a Boolean expression composed of @f[and], @f[or], and
@f[not] operators on (recursive) @i[feature] expressions.

For example, suppose that in implementation A the features @f[spice] and
@f[perq] are true, and in implementation B the feature @f[lispm] is true.
Then the expressions on the left below are read the same as those on the
right in implementation A:
@Lisp
@Tabset[45]
(cons #+spice "Spice" #+lispm "Lispm" x)@\(cons "Spice" x)
(setq a '(1 2 #+perq 43 #+(not perq) 27))@\(setq a '(1 2 43))
(let ((a 3) #+(or spice lispm) (b 3))@\(let ((a 3) (b 3))
   (foo a))@\   (foo a))
@Endlisp
In implementation B, however, they are read in this way:
@Lisp
@Tabset[45]
(cons #+spice "Spice" #+lispm "Lispm" x)@\(cons "Lispm" x)
(setq a '(1 2 #+perq 43 #+(not perq) 27))@\(setq a '(1 2 27))
(let ((a 3) #+(or spice lispm) (b 3))@\(let ((a 3) (b 3))
   (foo a))@\   (foo a))
@Endlisp

The @f[#+] construction must be used judiciously if unreadable code is
not to result.  The user should make a careful choice between read-time
conditionalization and run-time conditionalization.

The @f[#+] syntax operates by first reading the @i[feature] specification
and then skipping over the @i[form] if the @i[feature] is ``false.''
This skipping of a form is a bit tricky because of the possibility of
user-defined macro characters and side effects caused by the @f[#.] and 
@f[#,] constructions.  It is accomplished by binding the variable
@Var[read-suppress] to a non-@nil value and then calling the @f[read]
function.  See the description of @Varref[read-suppress] for the details
of this operation.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#-]@\@}
@f[#-@i[feature] @i[form]] is equivalent to @f[#+(not @i[feature]) @i[form]].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#|]@\@}
@f[#|...|#] is treated as a comment by the reader, just as everything
from a semicolon to the next newline is treated as a comment.
Anything may appear in the comment, except that it must be balanced
with respect to other occurrences of @f[#|] and @f[|#].
Except for this nesting rule, the comment may contain any characters
whatsoever.

The main purpose of this construct is to allow ``commenting out''
of blocks of code or data.  The balancing rule allows such blocks
to contain pieces already so commented out.  In this respect
the @f[#|...|#] syntax of @clisp differs from the @f[/*...*/] comment syntax
used by @pl1 and @clanguage.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#<]@\@}
This is not legal reader syntax.
It is used in the printed representation of objects that cannot
be read back in.  Attempting to read a @f[#<] will cause an error.
(More precisely, it @i[is] legal syntax, but the macro-character
function for it signals an error.)
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#]<space>,@f[ #]<tab>,@f[ #]<newline>,@f[ #]<page>,@f[ #]<return>@\@}
A @f[#] followed by a whitespace character is not legal reader syntax.
This prevents abbreviated forms produced via @Varref[print-level] cutoff
from reading in again, as a safeguard against losing
information.
(More precisely, this @i[is] legal syntax, but the macro-character
function for it signals an error.)
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[#)]@\@}
This is not legal reader syntax.
This prevents abbreviated forms produced via @Varref[print-level] cutoff
from reading in again, as a safeguard against losing information.
(More precisely, this @i[is] legal syntax, but the macro-character
function for it signals an error.)
@End[Multiple]
@End[Description]

@Subsection[The Readtable]
@label[READTABLE-SECTION]
@Index[readtable]

Previous sections describe the standard syntax accepted by the @f[read]
function.  This section discusses the advanced topic of altering the
standard syntax either to provide extended syntax for @xlisp objects
or to aid the writing of other parsers.

There is a data structure called the @i[readtable] that is used to
control the reader.  It contains information about the syntax of each
character equivalent to that in Table @Ref[Standard-Character-Syntax-Table].
It is set up exactly as in
Table @Ref[Standard-Character-Syntax-Table] to give the standard @clisp
meanings to all the characters, but the user can change the meanings of
characters to alter and customize the syntax of characters.  It is also
possible to have several readtables describing different syntaxes and to
switch from one to another by binding the variable @Var[readtable].

Even if an implementation supports characters with non-zero @i[bits] and @i[font] attributes,
it need not (but may) allow for such characters to have syntax
descriptions in the readtable.  However, every character of type
@f[string-char] must be represented in the readtable.

@Defvar[Var {readtable⎇]
The value of @Var[readtable] is the current readtable.  The initial
value of this is a readtable set up for standard @clisp syntax.
You can bind this variable to temporarily change the readtable being used.
@Enddefvar

To program the reader for a different syntax, a set of functions are
provided for manipulating readtables.  Normally, you should begin
with a copy of the standard @clisp readtable and then customize
the individual characters within that copy.

@Defun[Fun {copy-readtable⎇, Args {@optional @i[from-readtable] @i[to-readtable]⎇]
A copy is made of @i[from-readtable], which defaults to the current readtable
(the value of the global variable @Var[readtable]).  If @i[from-readtable]
is @false, then a copy of a standard @clisp readtable is made.
For example,
@Lisp
(setq @var[readtable] (copy-readtable nil))
@Endlisp
will restore the input syntax to standard @clisp syntax, even if
the original readtable has been clobbered (assuming it is not so
badly clobbered that you cannot type in the above expression!).
On the other hand,
@Lisp
(setq @var[readtable] (copy-readtable))
@Endlisp
will merely replace the current readtable with a copy of itself.

If @i[to-readtable] is unsupplied or @false, a fresh copy is made.  Otherwise,
@i[to-readtable] must be a readtable, which is destructively copied into.
@Enddefun

@Defun[Fun {readtablep⎇, Args {@i[object]⎇]
@Index2[P {readtable⎇, S {predicate⎇]
@f[readtablep] is true if its argument is a readtable,
and otherwise is false.
@Lisp
(readtablep x) @EQ (typep x 'readtable)
@Endlisp
@Enddefun

@Defun[Fun {set-syntax-from-char⎇, Args {@i[to-char] @i[from-char] @optional @i[to-readtable] @i[from-readtable]⎇]
This makes the syntax of @i[to-char] in @i[to-readtable] be the same as the
syntax of @i[from-char] in @i[from-readtable].  The @i[to-readtable]
defaults to the current readtable (the value of the global variable
@Varref[readtable]), and @i[from-readtable] defaults to @false, meaning
to use the syntaxes from the standard @xlisp readtable.

Only attributes as shown in
Table @Ref[Standard-Character-Syntax-Table] are copied; moreover,
if a @i[macro character] is copied, the macro definition function
is copied also.
However, attributes as shown
in Table @Ref[Standard-Readtable-Attributes-Table] are not copied;
they are ``hard-wired'' into the extended-token parser.
For example, if the definition of @f[S] is copied to @f[*],
then @f[*] will become a @i[constituent] that is
@i[alphabetic] but cannot be used
as an exponent indicator for short-format floating-point number syntax.

It ``works'' to copy a macro definition from a character such as
@f["] to another character; the standard definition for @f["]
looks for another character that is the same as the character that
invoked it.  It doesn't ``work'' to copy the definition of @f[(]
to @f[@lbrace], for example; it can be done, but it lets one write lists
in the form @f[@lbrace@;a b c)], not @f[@lbrace@;a b c@rbrace],
because the definition
always looks for a closing parenthesis, not a closing brace.  See the function
@Funref[read-delimited-list], which is useful in this connection.
@Enddefun

@Defun[Fun {set-macro-character⎇, Args {@i[char] @i[function] @optional @i[non-terminating-p] @i[readtable]⎇]
@Defun1[Fun {get-macro-character⎇, Args {@i[char] @optional @i[readtable]⎇]
@f[set-macro-character] causes @i[char] to be a macro character that
when seen by @f[read] causes @i[function] to be called.
If @i[non-terminating-p] is not @false (it defaults to @false),
then it will be a non-terminating macro character: it may be embedded
within extended tokens.
@f[set-macro-character] returns @true.

@f[get-macro-character] returns the function associated with @i[char]
and, as a second value, returns the @i[non-terminating-p] flag; it returns
@false if @i[char] does not have macro-character syntax.  In each case,
@i[readtable] defaults to the current readtable.

@i[function] is called with two arguments, @i[stream]
and @i[char].  The @i[stream] is the input stream, and @i[char] is the
macro character itself.
In the simplest case, @i[function] may return a @xlisp object.
This object is taken to be that whose printed representation
was the macro character and any following characters read
by the @i[function].
As an example, a plausible definition of the standard single quote
character is:
@Lisp
(defun single-quote-reader (stream char)
  (declare (ignore char))
  (list 'quote (read stream t nil t)))

(set-macro-character #\' #'single-quote-reader)
@Endlisp
(Note that @true is specified for the @i[recursive-p] argument
to @f[read]; see section @ref[CHARACTER-INPUT-SECTION].)
The function reads an object following the single-quote and returns
a list of the symbol @f[quote] and that object.
The @i[char] argument is ignored.

The function may choose instead to return @i[zero] values
(for example, by using @f[(values)] as the return expression).
In this case, the macro character and whatever it may have read
contribute nothing to the object being read.
As an example, here is a plausible definition for the standard semicolon
(comment) character:
@Lisp
(defun semicolon-reader (stream char)
  (declare (ignore char))
  ;; First swallow the rest of the current input line.
  ;; End-of-file is acceptable for terminating the comment.
  (do () ((char= (read-char stream nil #\Newline t) #\Newline)))
  ;; Return zero values.
  (values))

(set-macro-character #\; #'semicolon-reader)
@Endlisp
(Note that @true is specified for the @i[recursive-p] argument
to @f[read-char]; see section @ref[CHARACTER-INPUT-SECTION].)

The @i[function] should not have any side effects other than on the
@i[stream].
Because of backtracking and restarting of the @f[read] operation,
front ends (such as editors and
rubout handlers) to the reader may cause
@i[function] to be called repeatedly during the
reading of a single expression in which the macro character only appears
once.
@Incompatibility{The ability to return either zero or one value
is the closest @clisp macro characters come to the splicing macro
characters of @maclisp or the @f[splice] macro characters of @interlisp.
The @clisp definition does not allow the splicing of arbitrarily many
values, but it does allow a macro-character function to decide
after it is invoked whether or not to yield a value, an option not
possible in @maclisp or @interlisp.

@maclisp has nothing equivalent to non-terminating macro characters.
The @interlisp equivalents of terminating and non-terminating macro
characters are macro characters with the @f[ALWAYS] or @f[FIRST] option,
respectively.  @clisp has nothing equivalent to the @interlisp @f[ALONE]
macro-character option.
⎇
@Enddefun

@Defun[Fun {make-dispatch-macro-character⎇, Args {@i[char] @optional @i[non-terminating-p] @i[readtable]⎇]
This causes the character @i[char] to be a dispatching macro character
in @i[readtable] (which defaults to the current readtable).
If @i[non-terminating-p] is not @false (it defaults to @false),
then it will be a non-terminating macro character: it may be embedded
within extended tokens.
@f[make-dispatch-macro-character] returns @true.

Initially every character in the dispatch table has a character-macro
function that signals an error.  Use @f[set-dispatch-macro-character]
to define entries in the dispatch table.
@Enddefun

@Defun[Fun {set-dispatch-macro-character⎇, Args {@i[disp-char] @i[sub-char] @i[function] @optional @i[readtable]⎇]
@Defun1[Fun {get-dispatch-macro-character⎇, Args {@i[disp-char] @i[sub-char] @optional @i[readtable]⎇]
@f[set-dispatch-macro-character]
causes @i[function] to be called when the @i[disp-char]
followed by @i[sub-char] is read.  The @i[readtable] defaults to the
current readtable.  The arguments and return values for @i[function] are
the same as for normal macro characters
except that @i[function] gets @i[sub-char], not @i[disp-char],
as its second argument and also receives a third
argument that is the non-negative integer whose decimal
representation appeared between
@i[disp-char] and @i[sub-char], or @false if no decimal integer appeared
there.

The @i[sub-char] may not be one of the ten decimal digits;
they are always reserved for specifying an infix integer argument.
Moreover, if @i[sub-char] is a lowercase character
(see @Funref[lower-case-p]), its uppercase equivalent is used instead.
(This is how the rule is enforced that the case of a dispatch sub-character
doesn't matter.)

@f[set-dispatch-macro-character] returns @true.

@f[get-dispatch-macro-character] returns the macro-character function
for @i[sub-char] under @i[disp-char], or @nil if there is no
function associated with @i[sub-char].

If the @i[sub-char] is one of the ten decimal digits,
@f[get-dispatch-macro-character] always returns @nil.
If @i[sub-char] is a lowercase character,
its uppercase equivalent is used instead.

For either function,
an error is signalled if the specified @i[disp-char] is not in fact
a dispatch character in the specified readtable.  It is necessary
to use @Funref[make-dispatch-macro-character] to set up the
dispatch character before specifying its sub-characters.

As an example, suppose one would like @f[#$@i[foo]] to be read
as if it were @f[(dollars @i[foo])].  One might say:
@Lisp
(defun |#$-reader| (stream subchar arg)
  (declare (ignore subchar arg))
  (list 'dollars (read stream t nil t)))

(set-dispatch-macro-character #\# #\$ #'|#$-reader|)
@Endlisp
@Enddefun

@Incompatibility{This macro-character mechanism is different from
those in @maclisp, @interlisp, and @lmlisp.  Recently @xlisp systems have
implemented very general readers, even readers so programmable that they
can parse arbitrary compiled @c[bnf] grammars.  Unfortunately, these
readers can be complicated to use.  This design is an attempt to make the
reader as simple as possible to understand, use, and implement.
Splicing macros have been eliminated; a recent informal poll indicates
that no one uses them to produce other than zero or one value.  The
ability to access parts of the object preceding the macro character have
been eliminated.  The @maclisp single-character-object feature has been
eliminated because it is seldom used and trivially obtainable by
defining a macro.

The user is encouraged to turn off most macro characters, turn
others into single-character-object macros, and then use @f[read]
purely as a lexical analyzer on top of which to build a parser.
It is unnecessary, however, to cater to more complex lexical analysis
or parsing than that needed for @clisp.⎇

@Subsection[What the Print Function Produces]
@label[PRINTER]
@index[printer]

The @clisp printer is controlled by a number of special variables.
These are referred to in the following discussion
and are fully documented at the end of this section.

How an expression is printed depends on its data type, as described
in the following paragraphs.

@Begin[Description, Leftmargin +.2in, Indent -.2 in]
@Begin[Multiple]
@i[Integers]@\@}
If appropriate, a radix specifier may be printed; see the
variable @Varref[print-radix].
If an integer is negative, a minus sign is printed and then the
absolute value of the integer is printed.
Integers are printed in the radix specified by the
variable @Varref[print-base]
in the usual positional notation, most significant digit first.
The number zero is represented
by the single digit @f[0] and never has a sign.
A decimal point may then be printed, depending on the value
of @Varref[print-radix].
@End[Multiple]

@Begin[Multiple]
@i[Ratios]@\@}
If appropriate, a radix specifier may be printed; see the variable
@Varref[print-radix].
If the ratio is negative, a minus sign is printed.
Then the absolute value of the numerator is printed, as for an integer;
then a @f[/]; then the denominator.  The numerator and denominator are
both printed in the radix specified by the variable @Varref[print-base]; they are obtained as if by
the @Funref[numerator] and @Funref[denominator] functions, and so ratios
are always printed in reduced form (lowest terms).
@End[Multiple]

@Begin[Multiple]
@i[Floating-point numbers]@\@}
If the sign of the number (as determined by the function @Funref[float-sign])
is negative, then a minus sign is printed.  Then the magnitude is
printed in one of two ways.
If the magnitude of the
floating-point number is either zero or between 10@+[@superminussign@;3] (inclusive)
and 10@+[7] (exclusive), it may be printed as
the integer part of the number, then a decimal point,
followed by the fractional part of the number; there is always at least one
digit on each side of the decimal point.
If the format of the number does not match that specified by the variable
@Varref[read-default-float-format], then the exponent marker for
that format and the digit @f[0] are also printed.
For example, the base of the natural logarithms as a short-format
floating-point number might be printed as @f[2.71828S0].

For non-zero magnitudes
outside of the range 10@+[@superminussign@;3]
to 10@+[7], a floating-point number
will be printed in ``computerized scientific
notation.''  The representation of the number is scaled to be between
1 (inclusive) and 10 (exclusive) and then printed, with one digit
before the decimal point and at least one digit after the decimal point.
Next the exponent marker for the format is printed,
except that
if the format of the number matches that specified by the variable
@Varref[read-default-float-format], then the exponent marker @f[E]
is used.
Finally, the power of ten by which the fraction must be multiplied
to equal the original number is printed as a decimal integer.
For example, Avogadro's number as a short-format floating-point number
might be printed as @f[6.02S23].
@End[Multiple]

@Begin[Multiple]
@i[Complex numbers]@\@}
A complex number is printed as @f[#C],
an open parenthesis,
the printed representation of its real part, a space,
the printed representation of its imaginary part, and finally
a close parenthesis.
@End[Multiple]

@Begin[Multiple]
@i[Characters]@\@}
When @Varref[print-escape] is @false, a character prints as itself;
it is sent directly to the output stream.
When @Var[print-escape] is not @false, then @f[#\] syntax is used.
For example, the
printed representation of the character @f[#\A] with control and meta
bits on would be @f[#\CONTROL-META-A], and that of @f[#\a] with
control and meta bits on would be @f[#\CONTROL-META-\a].
@End[Multiple]

@Begin[Multiple]
@i[Symbols]@\@}
When @Varref[print-escape] is @false, only the characters of the print name
of the symbol are output (but the case in which to print any
uppercase characters in the print name is controlled by the
variable @varref[print-case]).

The remaining paragraphs describing the printing of symbols cover
the situation when @Var[print-escape] is not @false.

Backslashes @f[\] and
vertical bars @f[|] are included as required.  In particular,
backslash or vertical-bar syntax is used when the name of
the symbol would be otherwise treated by the reader as a potential number
(see section @ref[PARSE-TOKENS-SECTION]).
In making this decision, it is assumed that the value of @varref[print-base]
being used for printing would be used as the value of @varref[read-base]
used for reading; the value of @var[read-base] at the time of printing
is irrelevant.  For example, if the value of @var[print-base] were @f[16]
when printing the symbol @f[face], it would have to be printed as
@f[\FACE] or @f[\Face] or @f[|FACE|], because the token
@f[face] would be read as a hexadecimal
number (decimal value 64206) if @var[read-base] were @f[16].

The case in which to print any
uppercase characters in the print name is controlled by the
variable @var[print-case].
As a special case, @nil may sometimes be printed as @f[()] instead,
when @Var[print-escape] and @Var[print-pretty] are both not @false.

Package prefixes may be printed (using colon syntax)
if necessary.
The rules for package qualifiers are as follows.
When the symbol is printed, if it is in the
keyword package, then it is printed with a preceding colon; otherwise, if
it is accessible in the current package, it is printed without any
qualification; otherwise, it is printed with qualification.
See chapter @ref[XPACK].

A symbol that is uninterned (has no home package) is printed
preceded by @f[#:] if the variables @Varref[print-gensym]
and @Varref[print-escape] are both non-@nil;
if either is @nil, then the symbol is printed without
a prefix, as if it were in the current package.

@Implementation{Because the @f[#:] syntax does not intern the
following symbol, it is necessary to use circular-list syntax
if @Varref[print-circle] is not @false and
the same uninterned symbol appears several times in an expression
to be printed.  For example, the result of
@lisp
(let ((x (make-symbol "FOO"))) (list x x))
@endlisp
would be printed as @f[(#:foo #:foo)] if @var[print-circle]
were @false, but as @f[(#1=#:foo #1#)] if @var[print-circle]
were not @false.⎇

The case in which symbols are printed is controlled by the variable
@Varref[print-case].
@End[Multiple]

@Begin[Multiple]
@i[Strings]@\@}
The characters of the string are output in order.
If @Varref[print-escape] is not @false, a double quote
is output before and after, and all
double quotes and single escape characters are preceded by backslash.
The printing of strings is not affected by @Varref[print-array].
If the string has a fill pointer, then only those characters below
the fill pointer are printed.
@End[Multiple]

@Begin[Multiple]
@i[Conses]@\@}
Wherever possible, list notation is preferred over dot
notation.  Therefore the following algorithm is used:
@Begin[Format, leftmargin +1in]
1. Print an open parenthesis, @f[(].
2. Print the @i[car] of the cons.
3. If the @i[cdr] is a cons, make it the current cons, print a space, and go to step 2.
4. If the @i[cdr] is not null, print a space, a dot, a space, and the @i[cdr].
5. Print a close parenthesis, @f[)].
@End[Format]

This form of printing is clearer than showing each individual cons
cell.  Although the two expressions below are equivalent,
and the reader will accept
either one and produce the same data structure, the printer will
always print such a data structure in the second form.
@lisp
(a . (b . ((c . (d . @nil)) . (e . @nil))))
(a b (c d) e)
@Endlisp
The printing of conses is affected by the variables @varref[print-level]
and @varref[print-length].
@End[Multiple]

@Begin[Multiple]
@i[Bit-vectors]@\@}
A bit-vector is printed as @f[#*] followed by the bits of the bit-vector
in order.  If @Varref[print-array] is @false, however, then the bit-vector is
printed in a format (using @f[#<]) that is concise but not readable.
If the bit-vector has a fill pointer, then only those bits below
the fill pointer are printed.
@End[Multiple]


@Begin[Multiple]
@i[Vectors]@\@}
Any vector other than a string or bit-vector is printed using
general-vector syntax; this means that information
about specialized vector representations will be lost.
The printed representation of a zero-length vector is @f[#()].  The
printed representation of a non-zero-length vector begins with @f[#(].
Following that, the first element of the vector is printed.  If
there are any other elements, they are printed in turn, with a space
printed before each additional element.  A close parenthesis
after the
last element terminates the printed representation of the vector.  The
printing of vectors is affected by the variables @varref[print-level] and
@varref[print-length].
If the vector has a fill pointer, then only those elements below
the fill pointer are printed.

If @Varref[print-array] is @false, however, then the vector is not printed
as described above, but
in a format (using @f[#<]) that is concise but not readable.
@End[Multiple]

@Begin[Multiple]
@i[Arrays]@\@}
Normally any array other than a vector is printed
using @f[#@i[n]A] format.  Let @i[n] be the rank of the array.
Then @f[#] is printed, then @i[n] as a decimal integer,
then @f[A], then @i[n] open parentheses.  Next the elements
are scanned in row-major order.  Imagine the array indices being
enumerated in odometer fashion, recalling that the dimensions
are numbered from 0 to @i[n]@minussign@;1.  Every time the index for
dimension @i[j] is incremented, the following actions are taken:
@Begin[Enumerate]
If @i[j] < @i[n]@minussign@;1, then print a close parenthesis.

If incrementing the index for dimension @i[j] caused it to equal
dimension @i[j], reset that index to zero and increment dimension
@i[j]@minussign@;1 (thereby performing these three steps recursively),
unless @i[j]=0, in which case simply terminate the entire algorithm.
If incrementing the index for dimension @i[j] did not cause it to
equal dimension @i[j], then print a space.

If @i[j] < @i[n]@minussign@;1, then print an open parenthesis.
@End[Enumerate]
This causes the contents to be printed in a format suitable for
the @Kwdref[F {make-array⎇, K {initial-contents⎇] argument to @f[make-array].
The lists effectively printed by this procedure are subject to
truncation by @Varref[print-level] and @Varref[print-length].

If the array is of a specialized type, containing bits or string-characters,
then the innermost lists generated by the algorithm given above may instead
be printed using bit-vector or string syntax, provided that these innermost
lists would not be subject to truncation by @f[prinlength].  For example,
a 3-by-2-by-4 array of string-characters that would ordinarily be printed as
@lisp
#3A(((#\s #\t #\o #\p) (#\s #\p #\o #\t))
    ((#\p #\o #\s #\t) (#\p #\o #\t #\s))
    ((#\t #\o #\p #\s) (#\o #\p #\t #\s)))
@endlisp
may instead be printed more concisely as
@lisp
#3A(("stop" "spot") ("post" "pots") ("tops" "opts"))
@endlisp

If @Varref[print-array] is @false, then the array is printed
in a format (using @f[#<]) that is concise but not readable.
@End[Multiple]

@Begin[Multiple]
@i[Random-states]@\@}
@clisp does not specify a specific syntax
for printing objects of type @f[random-state].  However, every implementation
must arrange to print a random-state object in such a way that,
within the same implementation of @clisp, the function @Funref[read]
can construct from the printed representation a copy of the random-state
object as if the copy had been made by @Funref[make-random-state].
@End[Multiple]

@Begin[Multiple]
@i[Pathnames]@\@}
@clisp does not specify a specific syntax
for printing objects of type @f[pathname].  However, every implementation
must arrange to print a pathname in such a way that,
within the same implementation of @clisp, the function @Funref[read]
can construct from the printed representation an equivalent
instance of the pathname object.
@End[Multiple]
@End[Description]

Structures defined by @Macref[defstruct] are printed under the
control of the @Kwd[print-function] option to @f[defstruct].
If the user does not provide a printing function explicitly,
then a default printing function is supplied that prints the structure
using @f[#S] syntax (see section @ref[SHARP-SIGN-MACRO-CHARACTER-SECTION]).

Any other types are printed in an implementation-dependent manner.  It is
recommended that printed representations of all such objects begin with
the characters @f[#<] and end with @f[>] so that the reader will
catch such objects and not permit them to be read under normal
circumstances.  It is specifically and purposely @i[not]
required that a @clisp implementation
be able to print an object of type @f[hash-table], @f[readtable],
@f[package], @f[stream], or @f[function] in a way that can be read back in
successfully by @f[read]; the use of @f[#<] syntax is especially
recommended for the printing of such objects.

When debugging or when frequently dealing with large or
deep objects at top level, the user may wish to restrict the printer
from printing large amounts of information.  The variables
@Var[print-level] and @Var[print-length] allow the user to control how deep
the printer will print and how many elements at a given level the
printer will print.  Thus the user can see enough of the object to
identify it without having to wade through the entire expression.

@Defvar[Var {print-escape⎇]
When this flag is @false, then escape characters are not output
when an expression is printed.  In particular, a symbol is printed
by simply printing the characters of its print name.
The function @Funref[princ] effectively binds @Var[print-escape] to @false.

When this flag is not @false, then an attempt is made to print an
expression in such a way that it can be read again to produce an
@f[equal] structure.
The function @Funref[prin1] effectively binds @Var[print-escape] to @true.
@Incompatibility{This flag controls what was called @i[slashification]
in @maclisp.⎇

The initial value of this variable is @true.
@Enddefvar

@Defvar[Var {print-pretty⎇]
When this flag is @false, then only a small amount of whitespace is
output when printing an expression.

When this flag is not @false, then the printer will endeavor to insert
extra whitespace where appropriate to make the expression more readable.

The initial value of @Var[print-pretty] is implementation-dependent.
@Enddefvar

@Defvar[Var {print-circle⎇]
When this flag is @false (the default), then the printing process proceeds
by recursive descent; an attempt to print a circular structure may lead
to looping behavior and failure to terminate.

When this flag is not @false, then the printer will endeavor to detect
cycles in the structure to be printed, and to use @f[#@i[n]=] and @f[#@i[n]#]
syntax to indicate the circularities.
@Enddefvar

@Defvar[Var {print-base⎇]
The value of @Var[print-base] determines in what radix the printer will print
rationals.  This may be any integer from @f[2] to @f[36], inclusive;
the default value is @f[10] (decimal radix).
For radices above @f[10], letters of the alphabet are used to represent
digits above @f[9].
@Incompatibility{@maclisp calls this variable @f[base], and its default value is @f[8], not @f[10].⎇
In both @maclisp and @clisp,
floating-point numbers are always printed in decimal, no matter what the value
of @Var[print-base].
@Enddefvar

@Defvar[Var {print-radix⎇]
If the variable @Var[print-radix] is non-@false, the printer will print a
radix specifier to indicate the radix in which it is printing a rational
number.  To prevent confusion of the letter @f[O] with the digit @f[0],
and of the letter @f[B] with the digit @f[8], the radix specifier
is always printed using lowercase letters.
For example, if the current base is twenty-four (decimal), the
decimal integer twenty-three would print as @f[#24rN].  If @Var[print-base]
is @f[2], @f[8], or @f[16], then the radix specifier used is @f[#b],
@f[#o], or @f[#x].  For integers, base ten is indicated by a trailing
decimal point instead of a leading radix specifier; for ratios, however,
@f[#10r] is used.  The default value of @Var[print-radix] is @false.
@enddefvar

@Defvar[Var {print-case⎇]
The @Funref[read] function normally converts lowercase characters
appearing in symbols to corresponding uppercase characters,
so that internally print
names normally contain only uppercase characters.
However, users may prefer to see output using lowercase letters
or letters of mixed case.
This variable controls the case (upper, lower, or mixed) in which to print
any uppercase characters in the names of symbols
when vertical-bar syntax is not used.
The value of @var[print-case] should be one of the keywords
@Kwd[upcase], @Kwd[downcase], or @Kwd[capitalize];
the initial value is @Kwd[upcase].

Lowercase characters in the internal print name
are always printed in lowercase, and are
preceded by a single escape character or enclosed by multiple
escape characters.
Uppercase characters in the internal print name
are printed in upper case, in lower case, or in mixed case
so as to capitalize words, according to the value of
@var[print-case].  The convention for what constitutes
a ``word'' is the same as for the function @Funref[string-capitalize].
@Enddefvar

@Defvar[Var {print-gensym⎇]
The @Var[print-gensym] variable controls whether the prefix @f[#:]
is printed before symbols that have no home package.
The prefix is printed if the variable is not @false.
The initial value of @Var[print-gensym] is @true.
@Enddefvar

@defvar[Var {print-level⎇]
@defvar1[Var {print-length⎇]
The @Var[print-level] variable controls how many levels deep a nested
data object will print.
If @Var[print-level] is @false (the initial value), then no control is exercised.
Otherwise, the value should be an integer, indicating the maximum level to
be printed.  An object to be printed is at level @f[0];
its components (as of a list or vector) are at level @f[1]; and so on.
If an object to be recursively printed has components and is at a level
equal to or greater than the value of @Var[print-level], then the object
is printed as simply @f[#].

The @Var[print-length] variable controls how many elements at a given level
are printed.  A value of @false (the initial value) indicates that there
be no limit to the number of components printed.  Otherwise, the value of
@Var[print-length] should be an integer.  Should the number of elements of a
data object exceed the value @Var[print-length], the printer will print three
dots, @f[...], in place of those elements beyond the number specified
by @Var[print-length].  (In the case of a dotted list, if the list contains
exactly as many elements as the value of @Var[print-length], and in addition
has the non-null atom terminating it, that terminating atom is printed
rather than printing three dots.)

@var[print-level] and @var[print-length] affect the printing not only of lists,
but also of vectors, arrays, and any other object printed with
a list-like syntax.  They do not affect the printing of symbols,
strings, and bit-vectors.

The @xlisp reader will normally signal an error when reading
an expression that has been abbreviated because of level or length limits.
This signal is given because the @f[#] dispatch character normally signals
an error when followed by whitespace or @f[)], and because @f[...]
is defined to be an illegal token, as are all tokens consisting
entirely of periods (other than the single dot used in dot notation).

As an example, here are the ways the object
@Lisp
(if (member x y) (+ (car x) 3) '(foo . #(a b c d "Baz")))
@Endlisp
would be printed for various values of @Var[print-level]=@i[v] and @Var[print-length]=@i[n].
@Lisp
@Tabset[+.2 in, +.2 in]
@ux[@i[v]@\@i[n]@\@i[output]]
0@\1@\#
1@\1@\(if ...)
1@\2@\(if # ...)
1@\3@\(if # # ...)
1@\4@\(if # # #)
2@\1@\(if ...)
2@\2@\(if (member x ...) ...)
2@\3@\(if (member x y) (+ # 3) ...)
3@\2@\(if (member x ...) ...)
3@\3@\(if (member x y) (+ (car x) 3) ...)
3@\4@\(if (member x y) (+ (car x) 3) '(foo . #(a b c d ...)))
@Endlisp
@Enddefvar

@defvar[Var {print-array⎇]
If @f[print-array] is @false, then the contents of arrays other than strings
are never printed.  Instead, arrays are printed in a concise form using
@f[#<] that gives enough information for the user to be able to
identify the array, but does not include the entire array contents.
If @f[print-array] is not @false, non-string arrays are printed using
@f[#(], @f[#*], or @f[#@i[n]A] syntax.
The initial value of @Var[print-array] is implementation-dependent.
@Enddefvar


@Section[Input Functions]

The input functions are divided into two groups: those that
operate on streams of characters and those that operate on
streams of binary data.

@Subsection[Input from Character Streams]
@label[CHARACTER-INPUT-SECTION]

Many character
input functions take optional arguments called @i[input-stream],
@i[eof-error-p], and @i[eof-value].  The @i[input-stream] argument is the
stream from
which to obtain input; if unsupplied or @false it defaults to the value of
the special variable @Varref[standard-input].  One may also specify @true
as a stream, meaning the value of the special variable
@Varref[terminal-io].

The @i[eof-error-p] argument
controls what happens if input is from a file (or any other
input source that has a definite end) and the end of the file is reached.
If @i[eof-error-p] is true (the default), an error will be signalled
at end of file.  If it is false, then no error is signalled, and instead
the function returns @i[eof-value].

Functions such as @Funref[read] that read the representation
of an object rather than a single
character will always signal an error, regardless of @i[eof-error-p], if
the file ends in the middle of an object representation.
For example, if a file does
not contain enough right parentheses to balance the left parentheses in
it, @f[read] will complain.  If a file ends in a symbol or a number
immediately followed by end-of-file, @f[read] will read the symbol or
number successfully and when called again will see the end-of-file and
only then act according to @i[eof-error-p].
Similarly, the function @Funref[read-line]
will successfully read the last line of a file even if that line
is terminated by end-of-file rather than the newline character.
If a file contains ignorable text at the end, such
as blank lines and comments, @f[read] will not consider it to end in the
middle of an object.
Thus an @i[eof-error-p] argument controls what happens
when the file ends @i[between] objects.

Many input functions also take an argument called @i[recursive-p].
If specified and not @nil, this argument specifies that
this call is not a ``top-level'' call to @f[read] but an imbedded call,
typically from the function for a macro character.
It is important to distinguish such recursive calls for three reasons.

First, a top-level call establishes the context within which the
@f[#@i[n]=] and @f[#@i[n]#] syntax is scoped.  Consider, for example,
the expression
@lisp
(cons '#3=(p q r) '(x y . #3#))
@endlisp
If the single quote macro character were defined in this way:
@lisp
(set-macro-character
  #\'
  #'(lambda (stream char)
      (declare (ignore char))
      (list 'quote (read stream))))
@endlisp
then the expression could not be read properly, because there would be no way
to know when @f[read] is called recursively by the first
occurrence of @f['] that the label @f[#3=] would be referred to
later in the containing expression.
There would be no way to know because @f[read]
could not determine that it was called by a macro-character function
rather than from ``top level.''  The correct way to define the single quote
macro character uses the @i[recursive-p] argument:
@lisp
(set-macro-character
  #\'
  #'(lambda (stream char)
      (declare (ignore char))
      (list 'quote (read stream t nil t))))
@endlisp

Second, a recursive call does not alter whether the reading process
is to preserve whitespace or not (as determined by whether the
top-level call was to @f[read] or @f[read-preserving-whitespace]).
Suppose again that single-quote had the first, incorrect, macro-character
definition shown above.  Then a call to @f[read-preserving-whitespace]
that read the expression @f['foo ] would fail to preserve the space
character following the symbol @f[foo] because the single-quote
macro character function calls @f[read], not @f[read-preserving-whitespace],
to read the following expression (in this case @f[foo]).
The correct definition, which passes the value @true for the @i[recursive-p]
argument to @f[read], allows the top-level call to determine
whether whitespace is preserved.

Third, when end-of-file is encountered and the @i[eof-error-p] argument
is not @nil, the kind of error that is signalled may depend on the value
of @i[recursive-p].  If @i[recursive-p] is not @nil, then the end-of-file
is deemed to have occurred within the middle of a printed representation;
if @i[recursive-p] is @nil, then the end-of-file may be deemed to have
occurred between objects rather than within the middle of one.


@Defun[Fun {read⎇, Args {@optional @i[input-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
@f[read] reads in the printed representation of a @xlisp object
from @i[input-stream], builds a corresponding @xlisp object, and returns
the object.

Note that when the variable @Varref[read-suppress] is not @nil,
then @f[read] reads in a printed representation as best it can,
but most of the work of interpreting the representation is avoided
(the intent being that the result is to be discarded anyway).
For example, all extended tokens produce the result @nil regardless
of their syntax.
@Enddefun

@Defvar[Var {read-default-float-format⎇]
The value of this variable must be a type specifier symbol for
a specific floating-point format; these include
@f[short-float], @f[single-float],
@f[double-float], @f[long-float], and may include implementation-specific
types as well.  The default value is @f[single-float].

@var[read-default-float-format]
indicates the floating-point format to be used
for reading floating-point numbers that have no exponent marker or have
@f[e] or @f[E] for an exponent marker.  (Other exponent markers
explicitly prescribe the floating-point format to be used.)
The printer also uses this variable to guide the choice of exponent
markers when printing floating-point numbers.
@Enddefvar

@Defun[Fun {read-preserving-whitespace⎇, Args {@optional @i[in-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
Certain printed representations given to @f[read], notably those of symbols
and numbers, require a delimiting character after them.  (Lists do not, because
the close parenthesis marks the end of the list.)
Normally @f[read] will throw away the delimiting character if it is a
whitespace character;
but @f[read] will preserve the character (using @Funref[unread-char]) if it is
syntactically meaningful, because it may be the start of the next expression.

The function @f[read-preserving-whitespace] is provided for some specialized
situations where it is desirable to determine precisely what character
terminated the extended token.

As an example, consider this macro-character definition:
@Lisp
(defun slash-reader (stream char)
  (declare (ignore char))
  (do ((path (list (read-preserving-whitespace stream))
	     (cons (progn (read-char stream nil nil t)
			  (read-preserving-whitespace
			     stream nil nil t))
		   path)))
      ((not (char= (peek-char nil stream nil nil t) #\/))
       (cons 'path (nreverse path)))))
(set-macro-character #\/ #'slash-reader)
@Endlisp
(This is actually a rather dangerous definition to make because
expressions such as @f[(/ x 3)] will no longer be read properly.
The ability to reprogram the reader syntax is very powerful and
must be used with caution.  This redefinition of @f[/] is shown
here purely for the sake of example.)

Consider now calling @f[read] on this expression:
@Lisp
(zyedh /usr/games/zork /usr/games/boggle)
@Endlisp
The @f[/] macro reads objects separated by more @f[/] characters;
thus @f[/usr/games/zork] is intended to read as @f[(path usr games zork)].
The entire example expression should therefore be read as
@Lisp
(zyedh (path usr games zork) (path usr games boggle))
@Endlisp
However, if @f[read] had been used instead of
@f[read-preserving-whitespace], then after the reading of the symbol
@f[zork], the following space would be discarded; the next call
to @f[peek-char] would see the following @f[/], and the loop would
continue, producing this interpretation:
@Lisp
(zyedh (path usr games zork usr games boggle))
@Endlisp
On the other hand, there are times when whitespace @i[should] be discarded.
If a command interpreter takes single-character commands,
but occasionally reads a @xlisp object, then if the whitespace
after a symbol is not discarded it might be interpreted as a command
some time later after the symbol had been read.

Note that @f[read-preserving-whitespace] behaves @i[exactly] like @f[read]
when the @i[recursive-p] argument is not @nil.  The distinction is established
only by calls with @i[recursive-p] equal to @nil or omitted.
@Enddefun

@Defun[Fun {read-delimited-list⎇, Args {@i[char] @optional @i[input-stream] @i[recursive-p]⎇]
This reads objects from @i[stream] until the next character after an object's
representation (ignoring whitespace characters and comments) is @i[char].
(The @i[char] should not have whitespace syntax in the current
readtable.)
A list of the objects read is returned.

To be more precise, @f[read-delimited-list] looks ahead at each step
for the next non-whitespace character and peeks at it
as if with @f[peek-char].  If it is @i[char], then the
character is consumed and the list of objects is returned.
If it is a constituent or escape character, then @f[read] is used
to read an object, which is added to the end of the list.
If it is a macro character, the associated macro function
is called; if the function returns a value, that value is added
to the list.  The peek-ahead process is then repeated.

This function is particularly useful for defining new macro characters.
Usually it is desirable for the terminating character @i[char] to be a
terminating macro character so that it may be used to delimit tokens;
however, @f[read-delimited-list] makes no attempt to alter the syntax
specified for @i[char] by the current readtable.  The user must make any
necessary changes to the readtable syntax explicitly.  The following
example illustrates this.

Suppose you wanted @f[#{@i[a] @i[b] @i[c] ... @i[z]@rbrace@;]
to read as a list of all pairs of the elements @i[a], @i[b], @i[c], @f[...],
@i[z]; for example:
@Lisp
#@lbrace@;p q z a@rbrace@;  @r[reads as]  ((p q) (p z) (p a) (q z) (q a) (z a))
@Endlisp
This can be done by specifying a macro-character definition for @f[#@lbrace@;]
that does two things: read in all the items up to the @f[@rbrace@;],
and construct the pairs.  @f[read-delimited-list] performs
the first task.
@Lisp
(defun |#@lbrace@;-reader| (stream char arg)
  (declare (ignore char arg))
  (mapcon #'(lambda (x)
	      (mapcar #'(lambda (y) (list (car x) y)) (cdr x)))
	  (read-delimited-list #\@rbrace@; stream t)))

(set-dispatch-macro-character #\# #\@lbrace@; #'|#@lbrace@;-reader|)

(set-macro-character #\@rbrace@; (get-macro-character #\) @nil))
@Endlisp
(Note that @true is specified for the @i[recursive-p] argument.)

It is necessary here to give a definition to the character @f[@rbrace@;] as
well to prevent it from being a constituent.
If the line
@lisp
(set-macro-character #\@rbrace@; (get-macro-character #\) @nil))
@endlisp
shown above were not included, then the @f[@rbrace@;] in
@lisp
#@lbrace@;p q z a@rbrace@;
@endlisp
would be considered a constituent character, part of the symbol named
@f[a@rbrace@;].  One could correct for this by putting a space before
the @f[@rbrace@;], but it is better simply to use the call to
@f[set-macro-character].

Giving @f[@rbrace@;] the same
definition as the standard definition of the character @f[)] has the
twin benefit of making it terminate tokens for use with @f[read-delimited-list]
and also making it illegal for use in any other context (that is, attempting to
read a stray @f[@rbrace@;] will signal an error).

Note that @f[read-delimited-list] does not take an @i[eof-error-p]
(or @i[eof-value])
argument.  The reason is that it is always an error
to hit end-of-file during the operation of @f[read-delimited-list].
@Enddefun

@Defun[Fun {read-line⎇, Args {@optional @i[input-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
@f[read-line] reads in a line of text terminated by a newline.
It returns the line as a character string (@i[without] the newline character).
This function is usually used to get a line of input from the user.
A second returned value is a flag that is false if the line was
terminated normally, or true if end-of-file terminated the (non-empty) line.
If end-of-file is encountered immediately (that is, appears to terminate
an empty line), then end-of-file processing is controlled in the
usual way by the @i[eof-error-p], @i[eof-value], and @i[recursive-p] arguments.

The corresponding output function is @Funref[write-line].
@Enddefun

@Defun[Fun {read-char⎇, Args {@optional @i[input-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
@f[read-char] inputs one character from @i[input-stream] and returns it
as a character object.

The corresponding output function is @Funref[write-char].
@Enddefun

@Defun[Fun {unread-char⎇, Args {@i[character] @optional @i[input-stream]⎇]
@f[unread-char] puts the @i[character] onto the front of @i[input-stream].
The @i[character] must be the same character that was most recently read
from the @i[input-stream].  The @i[input-stream] ``backs up'' over this
character; when a character is next read from @i[input-stream], it will
be the specified character followed by the previous contents of
@i[input-stream].  @f[unread-char] returns @false.

One may apply @f[unread-char] only to the character most recently
read from input-@i[stream].  Moreover, one may not invoke @f[unread-char]
twice consecutively without an intervening @f[read-char]
operation.  The result is that one may back up only by one character,
and one may not insert any characters into the input stream that were not already there.
@Rationale{This is not intended to be a general mechanism, but rather
an efficient mechanism for allowing the @xlisp reader and other parsers
to perform one-character lookahead in the input stream.
This protocol admits a wide variety of efficient implementations,
such as simply decrementing a buffer pointer.
To have to specify the character in the call to @f[unread-char] is
admittedly redundant, since at any given time there is only one character
that may be legally specified.  The redundancy is intentional,
again to give the implementation latitude.⎇
@Enddefun

@Defun[Fun {peek-char⎇, Args {@optional @i[peek-type] @i[input-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
What @f[peek-char] does depends on the @i[peek-type], which
defaults to @false.  With a @i[peek-type] of @false,
@f[peek-char] returns the next character to be read from 
@i[input-stream], without actually removing it from the input stream.
The next time input is done from @i[input-stream], the character will still
be there.  It is as if one had called @f[read-char] and then @f[unread-char]
in succession.

If @i[peek-type] is @true, then @f[peek-char] skips over whitespace
characters (but not comments!),
and then performs the peeking operation on the next
character.
This is useful for finding the (possible) beginning
of the next printed representation of a @xlisp object.
The last character examined (the one that starts an object)
is not removed from the input stream.

If @i[peek-type] is a character object, then @f[peek-char] skips
over input characters until a character that
is @Xfunref[X {char=⎇, L {char#&M⎇] to that object is found;
that character is left in the input stream.
@Enddefun

@Defun[Fun {listen⎇, Args {@optional @i[input-stream]⎇]
The predicate @f[listen] is true if there is a character
immediately available from @i[input-stream], and is false if not.
This is particularly useful when the stream obtains characters
from an interactive device such as a keyboard.  A call to @Funref[read-char]
would simply wait until a character was available, but @f[listen] can
sense whether or not input is available and allow the program to
decide whether or not to attempt input.  On a non-interactive stream,
the general rule is that @f[listen] is true except when at
end-of-file.
@Enddefun

@Defun[Fun {read-char-no-hang⎇, Args {@optional @i[input-stream] @i[eof-error-p] @i[eof-value] @i[recursive-p]⎇]
This function is exactly like @Funref[read-char], except
that if it would be necessary to wait in order to get a character (as
from a keyboard), @false is immediately returned without waiting.  This
allows one to efficiently check for input availability and get the
input if it is available.
This is different from the @Funref[listen] operation in
two ways.  First, @f[read-char-no-hang] potentially actually reads a character,
whereas @f[listen] never inputs a character.  Second,
@f[listen] does not distinguish between end-of-file and no input being
available, whereas @f[read-char-no-hang] does make that distinction, returning
@i[eof-value] at end-of-file (or signalling an error if no @i[eof-error-p]
is true) but always returning @false if no input
is available.
@Enddefun

@Defun[Fun {clear-input⎇, Args {@optional @i[input-stream]⎇]
This clears any buffered input associated with @i[input-stream].
It is primarily useful for clearing type-ahead from keyboards when
some kind of asynchronous error has occurred.  If this operation
doesn't make sense for the stream involved, then @f[clear-input]
does nothing.  @f[clear-input] returns @false.
@Enddefun

@Defun[Fun {read-from-string⎇,Args {@i[string] @optional @i[eof-error-p] @i[eof-value]⎇, Keys {[start][end]⎇, Morekeys {[preserve-whitespace]⎇]
The characters of @i[string] are given successively to the @xlisp reader,
and the @xlisp object built by the reader is returned.  Macro characters
and so on will all take effect.

The arguments @kwd[start] and @kwd[end] delimit a substring of @i[string]
beginning at the character indexed by @kwd[start] and up to but not
including the character indexed by @kwd[end].  By default @kwd[start] is @f[0]
(the beginning of the string) and @kwd[end] is @f[(length @i[string])].
This is the same as for other string functions.

The flag @kwd[preserve-whitespace], if provided and not @nil, indicates
that the operation should preserve whitespace as
for @Funref[read-preserving-whitespace].  It defaults to @nil.

As with other reading functions,
the arguments @i[eof-error-p] and @i[eof-value] control the action
if the end of the (sub)string is reached
before the operation is completed;
reaching the end of the string is treated as any other end-of-file event.

@Index2[P {Multiple values⎇, S {returned by @f[read-from-string]⎇]
@f[read-from-string] returns two values; the first is the object read,
and the second is the index of the first character in the string not
read.  If the entire string was read, the second result
will be either the length of
the string or one greater than the length of the string.  The parameter
@kwd[preserve-whitespace] may affect this second value.

@lisp
(read-from-string "(a b c)") @EV (a b c) @r [and] 7
@Endlisp
@Enddefun

@Defun[Fun {parse-integer⎇, Args {@i[string]⎇, Keys {[start][end][radix][junk-allowed]⎇]
This function examines the substring of @i[string] delimited by @kwd[start]
and @kwd[end] (which default to the beginning and end of the string).
It skips over whitespace characters and then attempts to
parse an integer.  The @kwd[radix] parameter defaults to @f[10]
and must be an integer between 2 and 36.

If @kwd[junk-allowed] is not @false, then the first value
returned is the value of the number parsed
as an integer or @false if no syntactically correct integer
was seen.

If @kwd[junk-allowed] is @false (the default), then the entire substring is scanned.
The returned value is the value of the number parsed as an integer.
An error is signalled if the substring does not consist entirely of
the representation of an integer, possibly surrounded on either side by
whitespace characters.

In either case, the second value is the index into the string of the delimiter
that terminated the parse, or it is the index beyond the substring if the
parse terminated at the end of the substring (as will always be the case if
@i[junk-allowed] is false).

Note that @f[parse-integer] does not recognize the syntactic radix-specifier
prefixes @f[#O], @f[#B], @f[#X], and @f[#@i[n]R], nor does it recognize
a trailing decimal point.  It permits only an optional sign
(@f[+] or @f[-]) followed
by a non-empty sequence of digits in the specified radix.
@Enddefun


@Subsection [Input from Binary Streams]

@clisp currently specifies only a very simple facility for binary input:
the reading of a single byte as an integer.

@Defun[Fun {read-byte⎇, Args {@i[binary-input-stream] @optional @i[eof-error-p] @i[eof-value]⎇]
@f[read-byte] reads one byte from the @i[binary-input-stream] and returns
it in the form of an integer.
@Enddefun

@Section [Output Functions]

The output functions are divided into two groups: those that
operate on streams of characters and those that operate on
streams of binary data.  The function @f[format] operates
on streams of characters but is described in a section
separate from the other character-output functions
because of its great complexity.

@Subsection [Output to Character Streams]

These functions all take an optional argument called @i[output-stream],
which is where to send the output.  If unsupplied or @false, @i[output-stream]
defaults to the value of the variable
@Varref[standard-output].  If it is @true, the value of the variable
@Varref[terminal-io] is used.

@Defun[Fun {write⎇, Args {@i[object]⎇, Keys {[stream][escape][radix][base]⎇,
 Morekeys {[circle][pretty][level][length]⎇,
 YetMoreKeys {[case][gensym][array]⎇]
The printed representation of @i[object] is written to the output stream
specified by @Kwd[stream], which defaults to the value of @Varref[standard-output].

The other keyword arguments specify values used to control the
generation of the printed representation.  Each defaults to the
value of the corresponding global variable: see @Varref[print-escape],
@Varref[print-radix], @Varref[print-base], @Varref[print-circle], @Varref[print-pretty],
@Varref[print-level], @Varref[print-length], @Varref[print-case],
@Varref[print-gensym],
and @Varref[print-array].
(This is the means by which these variables affect printing operations:
supplying default values for the @f[write] function.)
Note that the printing of symbols is also affected by the value
of the variable @Varref[package].

@f[write] returns @i[object].
@Enddefun

@Defun[Fun {prin1⎇, Args {@i[object] @optional @i[output-stream]⎇]
@Defun1[Fun {print⎇, Args {@i[object] @optional @i[output-stream]⎇]
@Defun1[Fun {pprint⎇, Args {@i[object] @optional @i[output-stream]⎇]
@Defun1[Fun {princ⎇, Args {@i[object] @optional @i[output-stream]⎇]
@f[prin1] outputs the printed representation of @i[object] to
@i[output-stream].  Escape characters are used as appropriate.
Roughly speaking, the output from @f[prin1] is suitable for input to
the function @Funref[read].  @f[prin1] returns @i[object].
@lisp
(prin1 @i[object] @i[output-stream])
   @EQ (write @i[object] :stream @i[output-stream] :escape t)
@Endlisp

@f[print] is just like @f[prin1] except that the printed representation
of @i[object] is preceded by a newline (see @Funref[terpri])
and followed by a space.
@f[print] returns @i[object].

@f[pprint] is just like @f[print] except that the trailing
space is omitted and the
@i[object] is printed with the @Varref[print-pretty] flag non-@nil
to produce ``pretty'' output.
@f[pprint] returns no values (that is, it returns what the expression
@f[(values)] returns: zero values).

@f[princ] is just like @f[prin1] except that the
output has no escape characters.  A symbol is printed as simply the characters
of its print name; a string is printed without surrounding double quotes;
and there may be differences for other data types as well.
The general rule is that output from @f[princ] is intended to look
good to people, while output from @f[prin1] is intended to
be acceptable to the function @Funref[read].
@f[princ] returns @i[object].
@lisp
(princ @i[object] @i[output-stream])
   @EQ (write @i[object] :@i[stream output-stream] :escape @false)
@Endlisp

@Incompatibility{In @maclisp, the functions @f[prin1], @f[print],
and @f[princ] return @true, not the argument @i[object].⎇
@Enddefun


@Defun[Fun {write-to-string⎇, Args {@i[object]⎇, Keys {[escape][radix][base]⎇,
 Morekeys {[circle][pretty][level][length]⎇,
 YetMoreKeys {[case][gensym][array]⎇]
@Defun1[Fun {prin1-to-string⎇, Args {@i[object]⎇]
@Defun1[Fun {princ-to-string⎇, Args {@i[object]⎇]
The object is effectively printed as if by @Funref[write],
@Funref[prin1], or @Funref[princ], respectively,
and the characters that would be output are made into a string
which is returned.
@Incompatibility{The @interlisp function @f[mkstring] corresponds
to the @clisp function @f[princ-to-string].⎇
@Enddefun

@Defun[Fun {write-char⎇, Args {@i[character] @optional @i[output-stream]⎇]
@f[write-char] outputs the @i[character] to @i[output-stream],
and returns @i[character].
@Enddefun


@Defun[Fun {write-string⎇, Args {@i[string] @optional @i[output-stream]⎇, Keys {[start][end]⎇]
@Defun1[Fun {write-line⎇, Args {@i[string] @optional @i[output-stream]⎇, Keys {[start][end]⎇]
@f[write-string] writes the characters of the specified
substring of @i[string] to
the @i[output-stream].  The @Kwd[start] and @Kwd[end] parameters
delimit a substring of @i[string] in the usual manner
(see chapter @ref[KSEQUE]).
@f[write-line] does the same thing, but then
outputs a newline afterwards.  (See @Funref[read-line].)
In either case, the @i[string] is returned (@i[not] the substring
delimited by @Kwd[start] and @Kwd[end]).

In some implementations these may be significantly
more efficient than an explicit loop using @f[write-char].
@Enddefun


@Defun[Fun {terpri⎇, Args {@optional @i[output-stream]⎇]
@Defun1[Fun {fresh-line⎇, Args {@optional @i[output-stream]⎇]
@f[terpri] outputs a newline to @i[output-stream].
It is identical in effect to
@lisp
(write-char #\Newline @i[output-stream])
@endlisp
@f[terpri] returns @false.

@f[fresh-line] is similar to @f[terpri] but outputs a newline
only if the stream is not already at the start of a line.
(If for some reason this cannot be determined, then a newline
is output anyway.)
This guarantees that the stream will be on a ``fresh line'' while
consuming as little vertical distance as possible.
@f[fresh-line] is a predicate that is true if it output a
newline, and otherwise false.
@Enddefun

@Defun[Fun {finish-output⎇, Args {@optional @i[output-stream]⎇]
@Defun1[Fun {force-output⎇, Args {@optional @i[output-stream]⎇]
@Defun1[Fun {clear-output⎇, Args {@optional @i[output-stream]⎇]
Some streams may be implemented in an asynchronous or buffered manner.
The function @f[finish-output] attempts to ensure that all output
sent to @i[output-stream] has reached its destination, and only then
returns @false.  @f[force-output] initiates the emptying of any
internal buffers but returns @nil without waiting for completion
or acknowledgment.

The function @f[clear-output], on the other hand, attempts to abort any
outstanding output operation in progress in order
to allow as little output as possible
to continue to the destination.  This is useful, for example, to abort
a lengthy output to the terminal when an asynchronous error occurs.
@f[clear-output] returns @false.

The precise actions of all three of these operations are
implementation-dependent.
@Enddefun

The function @Funref[format] is very useful for producing
nicely formatted text, producing good-looking messages, and so on.
@f[format] can generate a string or output to a stream.

@Subsection [Output to Binary Streams]

@clisp currently specifies only a very simple facility for binary output:
the writing of a single byte as an integer.

@Defun[Fun {write-byte⎇, Args {@i[integer] @i[binary-output-stream]⎇]
@f[write-byte] writes one byte, the value of @i[integer].
It is an error if @i[integer] is not of the type
specified as the @Kwd[element-type] argument to @Funref[open] when the stream
was created.
The value @i[integer] is returned.
@Enddefun


@SubSection[Formatted Output to Character Streams]
@Index[formatted output]

Formatted output is performed not only by the @f[format] function
itself, but by certain other functions that accept a control string
``the way @f[format] does.''  For example, error-signalling functions
such as @f[cerror] accept @f[format] control strings.

@Defun[Fun {format⎇, Args {@i[destination] @i[control-string] @rest @i[arguments]⎇]
@f[format] is used to produce formatted output.
@f[format] outputs the characters of @i[control-string],
except that a tilde (@f[@tilde]) introduces a directive.
The character after
the tilde, possibly preceded by prefix parameters and modifiers, specifies
what kind of formatting is desired.  Most directives use one or more
elements of @i[arguments] to create their output; the typical directive
puts the next element of @i[arguments] into the output, formatted in
some special way.  It is an error if no argument remains for a directive
requiring an argument, but it is not an error if one or more arguments
remain unprocessed by a directive.

The output is sent to @i[destination].  If @i[destination] is
@false, a string is created that contains the output; this string is
returned as the value of the call to @f[format].  In all other cases
@f[format] returns @false, performing output to @i[destination]
as a side effect.
If @i[destination] is a stream, the output is sent to it.  If
@i[destination] is @true, the output is sent to the stream
that is the value of the variable @Varref[standard-output].
If @i[destination] is a string with a fill pointer, then
in effect the output characters are added to the end of the string
(as if by use of @Funref[vector-push-extend]).
@Enddefun

The @f[format] function includes some extremely complicated and specialized
features.  It is not necessary to understand all or even most of its
features to use @f[format] effectively.  The beginner should
skip over anything in the following documentation that is not
immediately useful or clear.  The more sophisticated features are
there for the convenience of programs with complicated formatting
requirements.

A @f[format] directive consists of a tilde (@f[@tilde]),
optional prefix parameters
separated by commas, optional colon (@f[:]) and at-sign (@f[@@]) modifiers,
and a single character indicating what kind of directive this is.
The alphabetic case of the directive character is ignored.
The prefix parameters are generally integers,
notated as optionally signed decimal numbers.
Examples of control strings:
@Lisp
"@tilde@;S"        ;@r[This is an @f[S] directive with no parameters or modifiers.]
"@tilde@;3,-4:@@s"  ;@r[This is an @f[S] directive with two parameters, 3 and @minussign@;4,]
            ;  @r[and both the colon and at-sign flags.]
"@tilde@;,+4S"     ;@r[Here the first prefix parameter is omitted and takes]
            ;  @r[on its default value, while the second parameter is 4.]
@Endlisp
Sometimes a prefix parameter is used to specify a character, for
instance the padding character in a right- or left-justifying operation.
In this case a single quote (@f[']) followed by the desired
character may be used as a prefix parameter, to mean the character
object that is the character following the single quote.  For
example, you can use @f[@tilde@;5,'0d]
to print an integer in decimal radix in five columns with leading zeros,
or @f[@tilde@;5,'*d] to get leading asterisks.

In place of a prefix parameter to a directive, you can put the letter
@f[V] (or @f[v]), which takes an argument from @i[arguments] as a parameter to
the directive.  Normally this should be an integer or character object,
as appropriate.  This feature allows variable-width fields and the like.
If the argument used by a @f[V] parameter is @nil,
the effect is as if the parameter had been omitted.
You may also use the character @f[#] in place of a parameter; it
represents the number of arguments remaining to be processed.

It is an error to give a format directive more parameters than
it is described here as accepting.  It is also an error to give
colon or at-sign modifiers to a directive in a combination not
specifically described here as being meaningful.

Here are some relatively simple examples to give you the general
flavor of how @f[format] is used.
@Lisp
(format @false "foo") @EV "foo"

(setq x 5)

(format @false "The answer is @tilde@;D." x) @EV "The answer is 5."

(format @false "The answer is @tilde@;3D." x) @EV "The answer is   5."

(format @false "The answer is @tilde@;3,'0D." x) @EV "The answer is 005."

(format @false "The answer is @tilde@;:D." (expt 47 x))
				@EV "The answer is 229,345,007."
@Endlisp

@Lisp
(setq y "elephant")

(format @false "Look at the @tilde@;A!" y) @EV "Look at the elephant!"

(format @false "Type @tilde@;:C to @tilde@;A."
	(set-char-bit #\D :control t)
        "delete all your files")
   @EV "Type Control-D to delete all your files."
@Endlisp

@Lisp
(setq n 3)

(format @false "@tilde@;D item@tilde@;:P found." n) @EV "3 items found."

(format @false "@tilde@;R dog@tilde@;:@lbracket@;s are@tilde@;; is@tilde@;@rbracket@; here." n (= n 1))
      @EV "three dogs are here."

(format @false "@tilde@;R dog@tilde@;:*@tilde@;@lbracket@;s are@tilde@;; is@tilde@;:;s are@tilde@;@rbracket@; here." n)
      @EV "three dogs are here."

(format @false "Here @tilde@;@lbracket@;are@tilde@;;is@tilde@;:;are@tilde@;@rbracket@; @tilde@;:*@tilde@;R pupp@tilde@;:@@P." n)
      @EV "Here are three puppies."
@Endlisp

In the descriptions of the directives which follows,
the term @i[arg] in general
refers to the next item of the set of @i[arguments] to be processed.
The word or phrase at the beginning of each description is a mnemonic
(not necessarily an accurate one!) for the directive.
@Begin[Description, Leftmargin +.6in, Indent -.6in]
@Begin[Multiple, Spread 0.3]
@f[@tilde@;A]@\@Index"@f'@tilde@;A '(@i[Ascii]) format directive"@}
@i[Ascii].  An @i[arg], any @xlisp object, is printed without escape characters
(as by @Funref[princ]).  In particular, if @i[arg] is a string, its characters
will be output verbatim.
If @i[arg] is @nil it will
be printed as @false; the colon modifier
(@f[@tilde:A]) will cause an @i[arg] of @nil to be printed as @empty,
but if @i[arg] is a composite structure, such as a list or vector,
any contained occurrences of @nil will still be printed as @false.

@f[@tilde@;@i[mincol]A] inserts spaces on the right, if necessary, to make the
width at least @i[mincol] columns.  The @f[@@] modifier causes the spaces
to be inserted on the left rather than the right.

@f[@tilde@;@i[mincol],@i[colinc],@i[minpad],@i[padchar]A] is the full form of @f[@tilde@;A],
which allows elaborate control of the padding.
The string is padded on the right (or on the left if the
@f[@@] modifier is used) with at least @i[minpad] copies
of @i[padchar]; padding characters are then inserted @i[colinc] characters
at a time until the total width is at least @i[mincol].
The defaults are @f[0] for @i[mincol] and @i[minpad], @f[1] for @i[colinc],
and the space character for @i[padchar].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;S]@\@Index"@f'@tilde@;S '(@i[S-expression]) format directive"@}
@i[S-expression].
This is just like @f[@tilde@;A], but @i[arg] is printed @i[with] escape
characters (as by @Funref[prin1] rather than @f[princ]).  The output is
therefore suitable for input to @Funref[read].  @f[@tilde@;S] accepts
all the arguments and modifiers that @f[@tilde@;A] does.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;D]@\@Index"@f'@tilde@;D '(@i[Decimal]) format directive"@}
@i[Decimal].
An @i[arg], which should be an integer, is printed in decimal radix.
@f[@tilde@;D] will never put a decimal point after the number.

@f[@tilde@;@i[mincol]D] uses a column width of @i[mincol]; spaces are inserted on
the left if the number requires fewer than @i[mincol] columns for its digits
and sign.  If the number doesn't fit in @i[mincol] columns, additional columns
are used as needed.

@f[@tilde@;@i[mincol],@i[padchar]D] uses @i[padchar] as the pad character
instead of space.

If @i[arg] is not an integer, it is printed
in @f[@tilde@;A] format and decimal base.

The @f[@@] modifier causes the number's sign to be printed always; the default
is to print it only if the number is negative.
The @f[:] modifier causes commas to be printed between groups of three digits;
the third prefix parameter may be used to change the character used as the comma.
Thus the most general form of @f[@tilde@;D] is
@f[@tilde@;@i[mincol],@i[padchar],@i[commachar]D].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;B]@\@Index"@f'@tilde@;B '(@i[Binary]) format directive"@}
@i[Binary].
This is just like @f[@tilde@;D] but prints in binary radix (radix 2)
instead of decimal.  The full form is therefore
@f[@tilde@;@i[mincol],@i[padchar],@i[commachar]B].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;O]@\@Index"@f'@tilde@;O '(@i[Octal]) format directive"@}
@i[Octal].
This is just like @f[@tilde@;D] but prints in octal radix (radix 8)
instead of decimal.  The full form is therefore
@f[@tilde@;@i[mincol],@i[padchar],@i[commachar]O].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;X]@\@Index"@f'@tilde@;X '(@i[heXadecimal]) format directive"@}
@i[Hexadecimal].
This is just like @f[@tilde@;D] but prints in hexadecimal radix
(radix 16) instead of decimal.  The full form is therefore
@f[@tilde@;@i[mincol],@i[padchar],@i[commachar]X].
@Incompatibility{In @maclisp and @lmlisp the @f[@tilde@;X] directive
outputs a space, and @f[@tilde@;@i[n]X] outputs @i[n] spaces,
in a manner analogous to @fortran @f[X] format.
In @clisp the directive @f[@tilde@;@@T] is used for that purpose.⎇
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;R]@\@Index"@f'@tilde@;R '(@i[Radix]) format directive"@}
@i[Radix].
@f[@tilde@;@i[n]R] prints @i[arg] in radix @i[n].
The modifier flags and any remaining parameters are used as for
the @f[@tilde@;D] directive.
Indeed, @f[@tilde@;D] is the same as @f[@tilde@;10R].  The full form here is therefore
@f[@tilde@;@i[radix],@i[mincol],@i[padchar],@i[commachar]R].

If no arguments are given to @f[@tilde@;R], then an entirely different
interpretation is given.  The argument should be an integer;
suppose it is @f[4].
@Begin[Itemize]
@f[@tilde@;R] prints @i[arg] as a cardinal English number: @f[four].

@f[@tilde@;:R] prints @i[arg] as an ordinal English number: @f[fourth].

@f[@tilde@;@@R] prints @i[arg] as a Roman numeral: @f[IV].

@f[@tilde@;:@@R] prints @i[arg] as an old Roman numeral: @f[IIII].
@End[Itemize]
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;P]@\@Index"@f'@tilde@;P '(@i[Plural]) format directive"@}
@i[Plural].
If @i[arg] is not @f[eql] to the integer @f[1], a lowercase @f[s] is
printed; if @i[arg] is @f[eql] to @f[1], nothing is printed.  (Notice
that if @i[arg] is a floating-point @f[1.0], the @f[s] @i[is]
printed.)

@f[@tilde@;:P] does the same thing, after doing a @f[@tilde@;:*] to back up one argument;
that is, it prints a lowercase @f[s] if the @i[last] argument was not
@f[1].  This is useful after printing a number using @f[@tilde@;D].

@f[@tilde@;@@P] prints @f[y] if the argument is @f[1], or @f[ies] if it is
not.  @f[@tilde@;:@@P] does the same thing, but backs up first.
@Lisp
(format @false "@tilde@;D tr@tilde@;:@@P/@tilde@;D win@tilde@;:P" 7 1) @EV "7 tries/1 win"
(format @false "@tilde@;D tr@tilde@;:@@P/@tilde@;D win@tilde@;:P" 1 0) @EV "1 try/0 wins"
(format @false "@tilde@;D tr@tilde@;:@@P/@tilde@;D win@tilde@;:P" 1 3) @EV "1 try/3 wins"
@Endlisp
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;C]@\@Index"@f'@tilde@;C '(@i[Character]) format directive"@}
@i[Character].  The next @i[arg] should be a character; it is printed
according to the modifier flags.

@f[@tilde@;C] prints the character in an implementation-dependent
abbreviated format.  This format should be culturally compatible with the
host environment.

@f[@tilde@;:C] spells out the names of the control bits
and represents non-printing characters
by their names: @f[Control-Meta-F], @f[Control-Return], @f[Space].
This is a ``pretty'' format for printing characters.

@f[@tilde@;:@@C] prints what @f[@tilde@;:C] would, and then
if the character requires unusual shift keys on the keyboard to type it,
this fact is mentioned: @f[Control-@Sail[∂] (Top-F)].  This is the
format used for telling the user about a key he is expected to type,
in prompts, for instance.  The precise output may depend not only
on the implementation, but on the particular I/O devices in use.

@f[@tilde@;@@C] prints the character in a way that the @xlisp reader can understand,
using @f[#\] syntax.
@Rationale{In some implementations the @f[@tilde@;S] directive would
accomplish what @f[@tilde@;C] does,
but the @f[@tilde@;C] directive is compatible
with @xlisp dialects such as @maclisp that do not have a character data type.⎇
@End[Multiple]


@Begin[Multiple, Spread 0.3]
@f[@tilde@;F]@\@Index"@f'@tilde@;F '(@i[Fixed-format floating-point]) format directive"@}
@i[Fixed-format floating-point].
The next @i[arg] is printed as a floating-point
number.

The full form is @f[@tilde@;@i[w],@i[d],@i[k],@i[overflowchar],@i[padchar]F].
The parameter @i[w]
is the width of the field to be printed; @i[d] is the number
of digits to print after the decimal point; @i[k] is a scale factor
that defaults to zero.

Exactly @i[w] characters will
be output.  First, leading copies of the character @i[padchar]
(which defaults to a space) are printed, if necessary, to pad the
field on the left.
If the @i[arg] is negative, then a minus sign is printed;
if the @i[arg] is not negative, then a plus sign is printed
if and only if the @f[@@] modifier was specified.  Then a sequence
of digits, containing a single embedded decimal point, is printed;
this represents the magnitude of the value of @i[arg] times 10@+[@superi[k]],
rounded to @i[d] fractional digits.
(When rounding up and rounding down would produce printed values
equidistant from the scaled value of @i[arg], then the implementation
is free to use either one.  For example, printing the argument
@f[6.375] using the format @f[@tilde@;4,2F] may correctly produce
either @f[6.37] or @f[6.38].)
Leading zeros are not permitted, except that a single
zero digit is output before the decimal point if the printed value
is less than one, and this single zero digit is not output
after all if @i[w]=@i[d]+1.

If it is impossible to print the value in the required format in a field
of width @i[w], then one of two actions is taken.  If the
parameter @i[overflowchar] is specified, then @i[w] copies of that
parameter are printed instead of the scaled value of @i[arg].
If the @i[overflowchar] parameter is omitted, then the scaled value
is printed using more than @i[w] characters, as many more as may be
needed.

If the @i[w] parameter is omitted, then the field is of variable width.
In effect, a value is chosen
for @i[w] in such a way that no leading pad characters need to be printed
and exactly @i[d] characters will follow the decimal point.
For example, the directive @f[@tilde@;,2F] will print exactly
two digits after the decimal point and as many as necessary before the
decimal point.

If the parameter @i[d] is omitted, then there is no constraint
on the number of digits to appear after the decimal point.
A value is chosen for @i[d] in such a way that as many digits
as possible may be printed subject to the width constraint
imposed by the parameter @i[w] and the constraint that no trailing
zero digits may appear in the fraction, except that if the
fraction to be printed is zero, then a single zero digit should
appear after the decimal point if permitted by the width constraint.

If both @i[w] and @i[d] are omitted, then the effect is to print
the value using ordinary free-format output; @Funref[prin1] uses this format
for any number whose magnitude is either zero or between
10@+[@superminussign@;3] (inclusive) and 10@+[7] (exclusive).

If @i[w] is omitted, then if the magnitude of @i[arg] is so large (or, if
@i[d] is also omitted, so small) that more than 100 digits would have to
be printed, then an implementation is free, at its discretion, to print
the number using exponential notation instead, as if by the directive
@f[@tilde@;E] (with all parameters to @f[@tilde@;E] defaulted, not
taking their values from the @f[@tilde@;F] directive).

If @i[arg] is a rational number, then it is coerced to be a @f[single-float]
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.  However, note that if @i[w] and @i[d] are
unspecified and the number has no exact decimal representation,
for example @f[1/3], some precision cutoff must be chosen
by the implementation: only a finite number of digits may be printed.)

If @i[arg] is a complex number or some non-numeric
object, then it is printed using the format directive @f[@tilde@;@i[w]D],
thereby printing it in decimal radix and a minimum field width of @i[w].
(If it is desired to print each of the real part and imaginary part
of a complex number using a @f[@tilde@;F] directive, then this must
be done explicitly with two @f[@tilde@;F] directives and code to
extract the two parts of the complex number.)

Examples:
@lisp
(defun foo (x)
  (format nil "@tilde@;6,2F|@tilde@;6,2,1,'*F|@tilde@;6,2,,'?F|@tilde@;6F|@tilde@;,2F|@tilde@;F"
          x x x x x x))

(foo 3.14159)  @EV "  3.14| 31.42|  3.14|3.1416|3.14|3.14159"
(foo -3.14159) @EV " -3.14|-31.42| -3.14|-3.142|-3.14|-3.14159"
(foo 100.0)    @EV "100.00|******|100.00| 100.0|100.00|100.0"
(foo 1234.0)  @EV "1234.00|******|??????|1234.0|1234.00|1234.0"
(foo 0.006)    @EV "  0.01|  0.06|  0.01| 0.006|0.01|0.006"
@endlisp

@Incompatibility{The @f[@tilde@;F] directive is similar to the
@f[F@i[w].@i[d]] edit descriptor in @fortran.

The presence
or absence of the @f[@@] modifier corresponds to the effect of
the @fortran @f[SS] or @f[SP] edit descriptor; nothing in @clisp
corresponds to the @fortran @f[S] edit descriptor.

The scale factor
specified by the parameter @i[k] corresponds to the scale factor @i[k]
specified by the @fortran @f[@i[k]P] edit descriptor.

In @fortran, the leading zero that precedes the decimal point when
the printed value is less than one is optional; in @clisp, the implementation
is required to print that zero digit.

In @clisp, the @i[w] and @i[d]
parameters are optional; in @fortran, they are required.

In @clisp, the pad character and overflow character are user-specifiable;
in @fortran, they are always space and asterisk, respectively.

A @fortran implementation
is prohibited from printing a representation of negative zero;
@clisp permits the printing of such a representation when appropriate.

In @maclisp and @lmlisp, the @f[@tilde@;F] format directive takes
a single parameter: the number of digits to use in the printed
representation.  This incompatibility between
@clisp and @maclisp was introduced for the sake of cultural compatibility
with @fortran.⎇
@end[Multiple]


@Begin[Multiple, Spread 0.3]
@f[@tilde@;E]@\@Index"@f'@tilde@;E '(@i[Exponential floating-point]) format directive"@}
@i[Exponential floating-point].
The next @i[arg] is printed as a floating-point
number in exponential notation.

The full form is @f[@tilde@;@i[w],@i[d],@i[e],@i[k],@i[overflowchar],@i[padchar],@i[exponentchar]E].
The parameter @i[w]
is the width of the field to be printed; @i[d] is the number
of digits to print after the decimal point; @i[e] is the number
of digits to use when printing the exponent;
@i[k] is a scale factor that defaults to one (not zero).

Exactly @i[w] characters will
be output.  First, leading copies of the character @i[padchar]
(which defaults to a space) are printed, if necessary, to pad the
field on the left.
If the @i[arg] is negative, then a minus sign is printed;
if the @i[arg] is not negative, then a plus sign is printed
if and only if the @f[@@] modifier was specified.  Then a sequence
of digits, containing a single embedded decimal point, is printed.
The form of this sequence of digits depends on the scale factor @i[k].
If @i[k] is zero, then @i[d] digits are printed after the decimal
point, and a single zero digit appears before the decimal point if
the total field width will permit it.  If @i[k] is positive,
then it must be strictly less than @i[d]+2;  @i[k] significant digits
are printed before the decimal point, and @i[d]@minussign@;@i[k]+1
digits are printed after the decimal point.  If @i[k] is negative,
then it must be strictly greater than @minussign@;@i[d];
a single zero digit appears before the decimal point if
the total field width will permit it, and after the decimal point
are printed first
@minussign@;@i[k] zeros and then @i[d]+@i[k] significant digits.
The printed fraction must be properly rounded.
(When rounding up and rounding down would produce printed values
equidistant from the scaled value of @i[arg], then the implementation
is free to use either one.  For example, printing the argument
@f[637.5] using the format @f[@tilde@;8,2E] may correctly produce
either @f[6.37E+02] or @f[6.38E+02])

Following the digit sequence, the exponent is printed.
First the character parameter @i[exponentchar] is printed; if this
parameter is omitted, then the exponent marker that
@Funref[prin1] would use is printed, as determined from the
type of the floating-point number and the current value of
@Varref[read-default-float-format].
Next, either a plus sign or a minus sign
is printed, followed by @i[e] digits representing the power of
ten by which the printed fraction must be multiplied
to properly represent the rounded value of @i[arg].

If it is impossible to print the value in the required format in a field
of width @i[w], possibly because @i[k] is too large or too small
or because the exponent cannot be printed in @i[e] character positions,
then one of two actions is taken.  If the
parameter @i[overflowchar] is specified, then @i[w] copies of that
parameter are printed instead of the scaled value of @i[arg].
If the @i[overflowchar] parameter is omitted, then the scaled value
is printed using more than @i[w] characters, as many more as may be
needed; if the problem is that @i[d] is too small for the specified @i[k]
or that @i[e] is too small, then a larger value is used for @i[d] or @i[e]
as may be needed.

If the @i[w] parameter is omitted, then the field is of variable width.
In effect a value is chosen
for @i[w] in such a way that no leading pad characters need to be printed.

If the parameter @i[d] is omitted, then there is no constraint
on the number of digits to appear.
A value is chosen for @i[d] in such a way that as many digits
as possible may be printed subject to the width constraint
imposed by the parameter @i[w], the constraint of the scale factor @i[k],
and the constraint that no trailing
zero digits may appear in the fraction, except that if the
fraction to be printed is zero then a single zero digit should
appear after the decimal point.

If the parameter @i[e] is omitted, then the exponent is printed
using the smallest number of digits necessary to represent its value.

If all of @i[w], @i[d], and @i[e] are omitted, then the effect is to print
the value using ordinary free-format exponential-notation output;
@Funref[prin1] uses this format for any non-zero number whose magnitude
is less than 10@+[@superminussign@;3] or greater than or equal to 10@+[7].

If @i[arg] is a rational number, then it is coerced to be a @f[single-float]
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.  However, note that if @i[w] and @i[d] are
unspecified and the number has no exact decimal representation,
for example @f[1/3], some precision cutoff must be chosen
by the implementation: only a finite number of digits may be printed.)

If @i[arg] is a complex number or some non-numeric
object, then it is printed using the format directive @f[@tilde@;@i[w]D],
thereby printing it in decimal radix and a minimum field width of @i[w].
(If it is desired to print each of the real part and imaginary part
of a complex number using a @f[@tilde@;E] directive, then this must
be done explicitly with two @f[@tilde@;E] directives and code to
extract the two parts of the complex number.)

Examples:
@lisp
(defun foo (x)
  (format @nil
          "@tilde@;9,2,1,,'*E|@tilde@;10,3,2,2,'?,,'$E|@tilde@;9,3,2,-2,'%@@E|@tilde@;9,2E"
          x x x x))

(foo 3.14159)  @EV "  3.14E+0| 31.42$-01|+.003E+03|  3.14E+0"
(foo -3.14159) @EV " -3.14E+0|-31.42$-01|-.003E+03| -3.14E+0"
(foo 1100.0)   @EV "  1.10E+3| 11.00$+02|+.001E+06|  1.10E+3"
(foo 1100.0L0) @EV "  1.10L+3| 11.00$+02|+.001L+06|  1.10L+3"
(foo 1.1E13)   @EV "*********| 11.00$+12|+.001E+16| 1.10E+13"
(foo 1.1L120)  @EV "*********|??????????|%%%%%%%%%|1.10L+120"
(foo 1.1L1200) @EV "*********|??????????|%%%%%%%%%|1.10L+1200"
@endlisp
As an example of the effects of varying the scale factor, the code
@lisp
(dotimes (k 13)
  (format t "}%Scale factor }2D: |}13,6,2,VE|"
	  (- k 5) 3.14159))
@endlisp
produces the following output:
@lisp
Scale factor -5: | 0.000003E+06|
Scale factor -4: | 0.000031E+05|
Scale factor -3: | 0.000314E+04|
Scale factor -2: | 0.003142E+03|
Scale factor -1: | 0.031416E+02|
Scale factor  0: | 0.314159E+01|
Scale factor  1: | 3.141590E+00|
Scale factor  2: | 31.41590E-01|
Scale factor  3: | 314.1590E-02|
Scale factor  4: | 3141.590E-03|
Scale factor  5: | 31415.90E-04|
Scale factor  6: | 314159.0E-05|
Scale factor  7: | 3141590.E-06|
@endlisp

@Incompatibility{The @f[@tilde@;E] directive is similar to the
@f[E@i[w].@i[d]] and @f[E@i[w].@i[d]E@i[e]]
edit descriptors in @fortran.

The presence
or absence of the @f[@@] modifier corresponds to the effect of
the @fortran @f[SS] or @f[SP] edit descriptor; nothing in @clisp
corresponds to the @fortran @f[S] edit descriptor.

The scale factor
specified by the parameter @i[k] corresponds to the scale factor @i[k]
specified by the @fortran @f[@i[k]P] edit descriptor;
note, however, that the default value for @i[k] is one in @clisp,
as opposed to the default value of zero in @fortran.
(On the other hand, note that a scale factor of one is used
for @fortran list-directed output, which is roughly
equivalent to using @f[@tilde@;E] with the @i[w], @i[d],
@i[e], and @i[overflowchar] parameters
omitted.)

In @clisp, the @i[w] and @i[d]
parameters are optional; in @fortran, they are required.

In @fortran, omitting @i[e] causes the exponent to be printed using
either two or three digits; if three digits are required, then the
exponent marker is omitted.  In @clisp, omitting @i[e] causes the
exponent to be printed using as few digits as possible; the exponent marker
is never omitted.

In @clisp, the pad character and overflow character are user-specifiable;
in @fortran they are always space and asterisk, respectively.

A @fortran implementation
is prohibited from printing a representation of negative zero;
@clisp permits the printing of such a representation when appropriate.

In @maclisp and @lmlisp, the @f[@tilde@;E] format directive takes
a single parameter: the number of digits to use in the printed
representation.  This incompatibility between
@clisp and @maclisp was introduced for the sake of cultural compatibility
with @fortran.⎇
@end[Multiple]


@Begin[Multiple, Spread 0.3]
@f[@tilde@;G]@\@Index"@f'@tilde@;G '(@i[General floating-point]) format directive"@}
@i[General floating-point].  The next @i[arg] is printed as a floating-point
number in either fixed-format or exponential notation as appropriate.

The full form is @f[@tilde@;@i[w],@i[d],@i[e],@i[k],@i[overflowchar],@i[padchar],@i[exponentchar]G].
The format in which to print @i[arg] depends on the magnitude (absolute
value) of the @i[arg].  Let @i[n] be an integer such that
10@+[@superi[n]@superminussign@;1]@sail[≤]@i[arg]@sail[<]10@+[@superi[n]].
Let @i[ee] equal @i[e]+2, or 4 if @i[e] is omitted.
Let @i[ww] equal @i[w]@minussign@;@i[ee],
or @nil if @i[w] is omitted.  If @i[d] is omitted, first let @i[q]
be the number of digits needed to print @i[arg] with no loss
of information and without leading or trailing zeros;
then let @i[d] equal @f[(max @i[q] (min @i[n] 7))].
Let @i[dd] equal @i[d]@minussign@;@i[n].

If 0@sail[≤]@i[dd]@sail[≤]@i[d], then @i[arg] is printed
as if by the format directives
@lisp
@tilde@;@i[ww],@i[dd],,@i[overflowchar],@i[padchar]F@tilde@;@i[ee]@@T
@endlisp
Note that the scale factor @i[k] is not passed to the @f[@tilde@;F]
directive.  For all other values of @i[dd], @i[arg] is printed as if
by the format directive
@lisp
@tilde@;@i[w],@i[d],@i[e],@i[k],@i[overflowchar],@i[padchar],@i[exponentchar]E
@endlisp

In either case, an @f[@@] modifier is specified to the @f[@tilde@;F]
or @f[@tilde@;E] directive if and only if one was specified to the
@f[@tilde@;G] directive.

Examples:
@lisp
(defun foo (x)
  (format @nil "@tilde@;9,2,1,,'*G|@tilde@;9,3,2,3,'?,,'$G|@tilde@;9,3,2,0,'%G|@tilde@;9,2G"
          x x x))

(foo 0.0314159) @EV "  3.14E-2|314.2$-04|0.314E-01|  3.14E-2"
(foo 0.314159)  @EV "  0.31   |0.314    |0.314    | 0.31    "
(foo 3.14159)   @EV "   3.1   | 3.14    | 3.14    |  3.1    "
(foo 31.4159)   @EV "   31.   | 31.4    | 31.4    |  31.    "
(foo 314.159)   @EV "  3.14E+2| 314.    | 314.    |  3.14E+2"
(foo 3141.59)   @EV "  3.14E+3|314.2$+01|0.314E+04|  3.14E+3"
(foo 3141.59L0) @EV "  3.14L+3|314.2$+01|0.314L+04|  3.14L+3"
(foo 3.14E12)   @EV "*********|314.2$+10|0.314E+13| 3.14L+12"
(foo 3.14L120)  @EV "*********|?????????|%%%%%%%%%|3.14L+120"
(foo 3.14L1200) @EV "*********|?????????|%%%%%%%%%|3.14L+1200"
@endlisp

@Incompatibility{The @f[@tilde@;G] directive is similar to the
@f[G@i[w].@i[d]] edit descriptor in @fortran.

The @clisp rules for deciding between the use of @f[@tilde@;F]
and @f[@tilde@;E] are compatible with the rules used by @fortran
but have been extended to cover the cases where @i[w] or @i[d]
is omitted or where @i[e] is specified.

In @maclisp and @lmlisp, the @f[@tilde@;G] format directive is equivalent
to the @clisp @f[@tilde@;@@*] directive.  This incompatibility between
@clisp and @maclisp was introduced for the sake of cultural compatibility
with @fortran.⎇
@end[Multiple]


@Begin[Multiple, Spread 0.3]
@f[@tilde@;$]@\@Index"@f'@tilde@;$ '(@i[Dollars]) format directive"@}
@i[Dollars floating-point].  The next @i[arg] is printed as a floating-point
number in fixed-format notation.  This format is particularly
convenient for printing a value as dollars and cents.

The full form is @f[@tilde@;@i[d],@i[n],@i[w],@i[padchar]$].
The parameter @i[d] is the number
of digits to print after the decimal point (default value 2);
@i[n] is the minimum number of digits to print before the decimal
point (default value 1);
@i[w] is the minimum total width of the field to be printed (default
value 0).

First padding and the sign are output.
If the @i[arg] is negative, then a minus sign is printed;
if the @i[arg] is not negative, then a plus sign is printed
if and only if the @f[@@] modifier was specified.  
If the @f[:] modifier is used, the sign appears before any padding,
and otherwise after the padding.
If @i[w] is specified and the number of other characters to be output
is less than @i[w], then copies of @i[padchar] (which defaults
to a space) are output to
make the total field width equal @i[w].
Then @i[n] digits are printed for the integer part of @i[arg],
with leading zeros if necessary; then a decimal point;
then @i[d] digits of fraction, properly rounded.

If the magnitude of @i[arg] is so large that more than @i[m] digits would
have to be printed, where @i[m] is the larger of @i[w] and 100, then an
implementation is free, at its discretion, to print the number using
exponential notation instead, as if by the directive
@f[@tilde@;@i[w],@i[q],,,,@i[padchar]E], where @i[w] and @i[padchar] are
present or omitted according to whether they were present or omitted in
the @f[@tilde@;$] directive, and where @i[q]=@i[d]+@i[n]@minussign@;1,
where @i[d] and @i[n] are the (possibly default) values given to the
@f[@tilde@;$] directive.

If @i[arg] is a rational number, then it is coerced to be a @f[single-float]
and then printed.  (Alternatively, an implementation is permitted to
process a rational number by any other method that has essentially the
same behavior but avoids such hazards as loss of precision or overflow
because of the coercion.)

If @i[arg] is a complex number or some non-numeric
object, then it is printed using the format directive @f[@tilde@;@i[w]D],
thereby printing it in decimal radix and a minimum field width of @i[w].
(If it is desired to print each of the real part and imaginary part
of a complex number using a @f[@tilde@;$] directive, then this must
be done explicitly with two @f[@tilde@;$] directives and code to
extract the two parts of the complex number.)
@End[Multiple]


@Begin[Multiple, Spread 0.3]
@f[@tilde@;%]@\@Index"@f'@tilde@;% '(new line) format directive"@}
This outputs a @f[#\Newline] character, thereby terminating the current
output line and beginning a new one
(see @Funref[terpri]).  @f[@tilde@;@i[n]%] outputs @i[n] newlines.
No @i[arg] is used.  Simply putting a newline in the control string
would work, but @f[@tilde@;%] is often used because it makes the control string
look nicer in the middle of a @xLisp program.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;&]@\@Index"@f'@tilde@;& '(fresh line) format directive"@}
Unless it can be determined that the output stream
is already at the beginning of a line,
this outputs a newline (see @Funref[fresh-line]).
@f[@tilde@;@i[n]&] calls @f[fresh-line]
and then outputs @i[n@Minussign@;1] newlines.
@f[@tilde@;0&] does nothing.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;|]@\@Index"@f'@tilde@;| '(new page) format directive"@}
This outputs a page separator character, if possible.
@f[@tilde@;@i[n]|] does this
@i[n] times.  @f[|] is vertical bar, not capital I.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;@tilde@;]@\@Index"@f'@tilde@;@tilde@; '(@i[Tilde]) format directive"@}
@i[Tilde].
This outputs a tilde.  @f[@tilde@;@i[n]@tilde@;] outputs @i[n] tildes.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;]<newline>@\@Index"@f'@tilde@;<newline> '(ignore whitespace) format directive"@}
Tilde immediately followed by a newline ignores the newline
and any following non-newline whitespace characters.
With a @f[:], the newline
is ignored, but any following whitespace is left in place.
With an @f[@@], the newline
is left in place, but any following whitespace is ignored.
This directive is typically used when a format control string is too long
to fit nicely into one line of the program:
@Lisp
(defun type-clash-error (fn nargs argnum right-type wrong-type)
  (format *error-output*
          "@tilde@;&Function @tilde@;S requires its @tilde@;:@lbracket@tilde@;:R@tilde@;;@tilde@;*@tilde@;@rbracket @tilde@;
           argument to be of type @tilde@;S,@tilde@;%but it was called @tilde@;
	   with an argument of type @tilde@;S.@tilde@;%"
	  fn (eql nargs 1) argnum right-type wrong-type))

(type-clash-error 'aref nil 2 'integer 'vector)  @r[prints]:
Function AREF requires its second argument to be of type INTEGER,
but it was called with an argument of type VECTOR.

(type-clash-error 'car 1 1 'list 'short-float)  @r[prints]:
Function CAR requires its argument to be of type LIST,
but it was called with an argument of type SHORT-FLOAT.
@Endlisp
Note that in this example newlines appear in the output only as specified
by the @f[@tilde@;&] and @f[@tilde@;%] directives; the actual newline characters
in the control string are suppressed because each is preceded by a tilde.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;T]@\@Index"@f'@tilde@;T '(@i[Tabulate]) format directive"@}
@i[Tabulate].
This spaces over to a given column.
@f[@tilde@;@i[colnum],@i[colinc]T] will output
sufficient spaces to move the cursor to column @i[colnum].  If the cursor
is already at or beyond column @i[colnum], it will output spaces to move it to
column @i[colnum]+@i[k]*@i[colinc] for the smallest positive integer
@i[k] possible, unless @i[colinc] is zero, in which case no spaces
are output if the cursor is already at or beyond column @i[colnum].
@i[colnum] and @i[colinc] default to @f[1].

Ideally, the current column position is determined by examination of the
destination, whether a stream or string. (Although no user-level
operation for determining the column position of a stream is defined
by @clisp, such a facility may exist at the implementation level.)
If for some reason the current absolute column position cannot be determined
by direct inquiry,
@f[format] may be able to deduce the current column position by noting
that certain directives (such as @f[@tilde@;%], or @f[@tilde@;}&],
or @f[@tilde@;A] with the argument being a string containing a newline) cause
the column position to be reset to zero, and counting the number of characters
emitted since that point.  If that fails, @f[format] may attempt a
similar deduction on the riskier assumption that the destination was
at column zero when @f[format] was invoked.  If even this heuristic fails
or is implementationally inconvenient, at worst
the @f[@tilde@;T] operation will simply output two spaces.
(All this implies that code that uses @f[format] is
more likely to be portable if all format control strings that use 
the @f[@tilde@;T] directive either begin with @f[@tilde@;%] or @f[@tilde@;&],
or are designed to be used only when the destination is known from other
considerations to be at column zero.)

@f[@tilde@;@@T] performs @i[relative] tabulation.
@f[@tilde@;@i[colrel],@i[colinc]@@T] outputs @i[colrel] spaces
and then outputs the smallest non-negative
number of additional spaces necessary to move the cursor
to a column that is a multiple
of @i[colinc].  For example, the directive @f[@tilde@;3,8@@T] outputs
three spaces and then moves the cursor to a ``standard multiple-of-eight
tab stop'' if not at one already.
If the current output column cannot be determined, however,
then @i[colinc] is ignored, and exactly @i[colrel] spaces are output.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;*]@\@Index"@f'@tilde@;* '(ignore argument) format directive"@}
The next @i[arg] is ignored.  @f[@tilde@;@i[n]*] ignores the next @i[n] arguments.

@f[@tilde@;:*] ``ignores backwards''; that is, it backs up in the list of
arguments so that the argument last processed will be processed again.
@f[@tilde@;@i[n]:*] backs up @i[n] arguments.

When within a @f[@tilde@;@lbrace@;] construct
(see below), the ignoring (in either direction) is relative to the list
of arguments being processed by the iteration.

@f[@tilde@;@i[n]@@*] is an ``absolute goto'' rather than a ``relative goto'':
it goes to the @i[n]th @i[arg], where 0 means the first one;
@i[n] defaults to 0, so @f[@tilde@;@@*] goes back to the first @i[arg].
Directives after a @f[@tilde@;@i[n]@@*]
will take arguments in sequence beginning with the one gone to.
When within a @f[@tilde@;@lbrace@;] construct, the ``goto''
is relative to the list of arguments being processed by the iteration.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;?]@\@Index"@f'@tilde@;? '(indirection) format directive"@}
@i[Indirection].
The next @i[arg] must be a string, and the one after it a list;
both are consumed by the @f[@tilde@;?] directive.
The string is processed as a @f[format] control string, with the
elements of the list as the arguments.  Once the recursive processing
of the control string has been finished, then processing of the control
string containing the @f[@tilde@;?] directive is resumed.
Example:
@lisp
(format nil "}? }D" "<}A }D>" '("Foo" 5) 7) @EV "<Foo 5> 7"
(format nil "}? }D" "<}A }D>" '("Foo" 5 14) 7) @EV "<Foo 5> 7"
@endlisp
Note that in the second example three arguments are supplied
to the control string @f["<}A }D>"], but only two are processed
and the third is therefore ignored.

With the @f[@@] modifier, only one @i[arg] is directly consumed.
The @i[arg] must be a string; it is processed as part of the control
string as if it had appeared in place of the @f[@tilde@;@@?] construct,
and any directives in the recursively processed control string may
consume arguments of the control string containing the @f[@tilde@;@@?]
directive.
Example:
@lisp
(format nil "}@@? }D" "<}A }D>" "Foo" 5 7) @EV "<Foo 5> 7"
(format nil "}@@? }D" "<}A }D>" "Foo" 5 14 7) @EV "<Foo 5> 14"
@endlisp

Here is a rather sophisticated example.
The @f[format] function itself,
as implemented at one time in @lmlisp,
used a routine internal to the @f[format] package called @f[format-error] to
signal error messages; @f[format-error] in turn used @f[error], which used
@f[format] recursively.  Now @f[format-error] took a string and
arguments, just like @f[format], but also printed the control string
to @f[format] (which at this point was available
in the global variable @var[ctl-string]) and a little
arrow showing where in the processing of the control string the error
occurred.  The variable @var[ctl-index] pointed one character after the
place of the error.
@Lisp
(defun format-error (string &rest args)	   ;Example
  (error @false "@tilde@;?@tilde@;%@tilde@;V@@T@Sail[↓]@tilde@;%@tilde@;3@@T\"@tilde@;A\"@tilde@;%"
	 string args (+ *ctl-index* 3) *ctl-string*))
@Endlisp
(The character set used in the @lmlisp implementation contains a
down-arrow character @sail[↓], which is not a standard @clisp
character.)  This first processed the given string and arguments using
@f[@tilde@;?], then output a newline, tabbed a variable amount for
printing the down-arrow, and printed the control string between
double quotes (note the use of @f[\"] to include double quotes within
the control string).  The effect was something like this:
@Lisp
(format t "The item is a @tilde@;@lbracket@;Foo@tilde@;;Bar@tilde@;;Loser@tilde@;@rbracket@;." 'quux)
>>ERROR: The argument to the FORMAT "@tilde@;@lbracket@;" command 
         must be a number.
                   @Sail[↓]
   "The item is a @tilde@;@lbracket@;Foo@tilde@;;Bar@tilde@;;Loser@tilde@;@rbracket@;."
...
@Endlisp
@Implementation{Implementors may wish to report errors occurring
within @f[format] control strings in the manner outlined here.
It looks pretty flashy when done properly.⎇
@End[Multiple]
@End[Description]

The format directives after this point are much more complicated than the
foregoing; they constitute control structures that can perform
case conversion,
conditional selection, iteration, justification, and non-local exits.
Used with restraint, they can perform powerful tasks.  Used with
abandon, they can produce completely unreadable and unmaintainable code.

The case-conversion, conditional, iteration, and justification
constructs can contain other formatting constructs by bracketing them.
These constructs must nest properly with respect to each other.
For example, it is not legitimate to put the start of a case-conversion
construct in each arm of a conditional and the
end of the case-conversion construct outside the conditional:
@lisp
@tabset[54]
(format @false "@tilde@;:@lbracket@;abc@tilde@;:@@(def@tilde@;;ghi@tilde@;:@@(jkl@tilde@;@rbracket@;mno@tilde@;)" x)@\;@r[Illegal!]
@endlisp
One might expect this to produce either @f["abcDEFMNO"] or @f["ghiJKLMNO"],
depending on whether @f[x] is false or true; but in fact the construction
is illegal because the @f{@tilde@;@lbracket@;...@tilde@;;...@tilde@;@rbracket@;⎇
and @f[@tilde@;(...@tilde@;)] constructs are not properly nested.

The processing indirection caused by the @f[@tilde@;?] directive
is also a kind of nesting for the purposes of this rule of proper nesting.
It is not permitted to
start a bracketing construct within a string processed
under control of a @f[@tilde@;?]
directive and end the construct at some point after the @f[@tilde@;?] construct
in the string containing that construct, or vice versa.
For example, this situation is illegal:
@lisp
@tabset[40]
(format @false "@tilde@;?ghi@tilde@;)" "abc@tilde@;@@(def")@\;@r[Illegal!]
@endlisp
One might expect it to produce @f["abcDEFGHI"], but in fact the construction
is illegal because the @f[@tilde@;?]
and @f[@tilde@;(...@tilde@;)] constructs are not properly nested.

@Begin[Description, Leftmargin +.6in, Indent -.6in]
@Begin[Multiple, Spread 0.3]
@f[@tilde@;(@i[str]@tilde@;)]@\@}
@i[Case conversion].
@Index"@f'@tilde@;( '(case conversion) format directive"
The contained control string @i[str] is processed, and what it produces
is subject to case conversion.

With no flags, every uppercase character
are converted to the corresponding lowercase character.

@f[@tilde@;:(] capitalizes all words, as if by @Funref[string-capitalize].

@f[@tilde@;@@(] capitalizes just the first word and forces the rest to lower
case.

@f[@tilde@;:@@(] converts every lowercase character
to the corresponding uppercase character.

In this example @f[@tilde@;@@(] is used to cause the first word
produced by @f[@tilde@;@@R] to be capitalized:
@lisp
(format nil "@tilde@;@@R @tilde@;(@tilde@;@@R@tilde@;)" 14 14) @EV "XIV xiv"
(defun f (n) (format nil "@tilde@;@@(@tilde@;R@tilde@;) error@tilde@;:P detected." n))
(f 0) @EV "Zero errors detected."
(f 1) @EV "One error detected."
(f 23) @EV "Twenty-three errors detected."
@endlisp
@end[multiple]

@Begin[Multiple, Spread 0.3]
@f{@tilde@;@lbracket@;@i[str0]@tilde@;;@i[str1]@tilde@;;@i[...]@tilde@;;@i[strn]@tilde@;@rbracket@;⎇@\@}
@i[Conditional expression].
@Index"@f'@tilde@;@lbracket@; '(conditional) format directive"
This is a set of control strings, called @i[clauses], one of which is
chosen and used.  The clauses are separated by @f[@tilde@;;] and the construct
is terminated by @f{@tilde@;@rbracket@;⎇.  For example,
@Lisp
"@tilde@;@lbracket@;Siamese@tilde@;;Manx@tilde@;;Persian@tilde@;@rbracket@; Cat"
@Endlisp
The @i[arg]th
clause is selected, where the first clause is number 0.
If a prefix parameter is given (as @f{@tilde@;@i[n][⎇),
then the parameter is used instead of an argument.
(This is useful only if the parameter is specified by @f[#],
to dispatch on the number of arguments remaining to be processed.)
If @i[arg] is out of range then no clause is selected
(and no error is signalled.).
After the selected alternative has been processed, the control string
continues after the @f{@tilde@;@rbracket@;⎇.

@f{@tilde@;@lbracket@;@i[str0]@tilde@;;@i[str1]@tilde@;;@i[...]@tilde@;;@i[strn]@tilde@;:;@i[default]@tilde@;@rbracket@;⎇ has a default case.
If the @i[last] @f[@tilde@;;] used to separate clauses
is @f[@tilde@;:;] instead, then the last clause is an ``else'' clause
that is performed if no other clause is selected.
For example:
@Lisp
"@tilde@;@lbracket@;Siamese@tilde@;;Manx@tilde@;;Persian@tilde@;:;Alley@tilde@;@rbracket@; Cat"
@Endlisp

@f{@tilde@;:@lbracket@;@i[false]@tilde@;;@i[true]@tilde@;@rbracket@;⎇ selects the @i[false] control string
if @i[arg] is @false, and selects the @i[true] control string otherwise.

@f{@tilde@;@@@lbracket@;@i[true]@tilde@;@rbracket@;⎇ tests the argument.  If it is not @false,
then the argument is not used up by the @f{@tilde@@@lbracket@;⎇ command
but remains as the next one to be processed,
and the one clause @i[true] is processed.
If the @i[arg] is @false, then the argument is used up,
and the clause is not processed.
The clause therefore should normally use exactly one argument,
and may expect it to be non-@false.
For example:
@Lisp
(setq @Var[print-level] @false @var[print-length] 5)
(format @false
        "@tilde@;@@@lbracket@; print level = @tilde@;D@tilde@;@rbracket@;@tilde@;@@@lbracket@; print length = @tilde@;D@tilde@;@rbracket@;"
	@var[print-level] @var[print-length])
   @EV  " print length = 5"
@Endlisp

The combination of @f[@tilde@;@lbracket@;] and @f[#] is useful, for
example, for dealing with English conventions for printing lists:
@Lisp
(setq foo "Items:@tilde@;#[ none@tilde@;; @tilde@;S@tilde@;; @tilde@;S and @tilde@;S@tilde@;
           @tilde@;:;@tilde@;@@@lbrace@;@tilde@;#[@tilde@;; and@tilde@;@rbracket@; @tilde@;S@tilde@;↑,@tilde@;@rbrace@;@tilde@;@rbracket@;.")
(format @false foo)
	@EV  "Items: none."
(format @false foo 'foo)
	@EV  "Items: FOO."
(format @false foo 'foo 'bar)
	@EV  "Items: FOO and BAR."
(format @false foo 'foo 'bar 'baz)
	@EV  "Items: FOO, BAR, and BAZ."
(format @false foo 'foo 'bar 'baz 'quux)
	@EV  "Items: FOO, BAR, BAZ, and QUUX."
@Endlisp
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;;]@\@}
This separates clauses in @f{@tilde@;@lbracket@;⎇ and @f[@tilde@;<]
constructions.  It is an error elsewhere.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f{@tilde@;@rbracket@;⎇@\@}
This terminates a @f{@tilde@;@lbracket@;⎇.  It is an error elsewhere.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;@lbrace@;@i[str]@tilde@;@rbrace@;]@\@}
@i[Iteration].
@Index"@f'@tilde@;@lbrace@; '(iteration) format directive"
This is an iteration construct.  The argument should be a list,
which is used as a set of arguments as if for a recursive call to @f[format].
The string @i[str] is used repeatedly as the control string.
Each iteration can absorb as many elements of the list as it likes
as arguments;
if @i[str] uses up two arguments by itself, then two elements of the
list will get used up each time around the loop.
If before any iteration step the list is empty, then the iteration is terminated.
Also, if a prefix parameter @i[n] is given, then there will be at most @i[n]
repetitions of processing of @i[str].  Finally, the @f[@tilde@;↑] directive can be
used to terminate the iteration prematurely.

Here are some simple examples:
@Lisp
(format @false "The winners are:@tilde@;@lbrace@; @tilde@;S@tilde@;@rbrace@;."
	'(fred harry jill))
     @EV "The winners are: FRED HARRY JILL."
(format @false "Pairs:@tilde@;@lbrace@; <@tilde@;S,@tilde@;S>@tilde@;@rbrace@;." '(a 1 b 2 c 3))
     @EV "Pairs: <A,1> <B,2> <C,3>."
@Endlisp

@f[@tilde@;:@lbrace@;@i[str]@tilde@;@rbrace@;] is similar, but the argument should be a list of sublists.
At each repetition step, one sublist is used as the set of arguments for
processing @i[str]; on the next repetition, a new sublist is used, whether
or not all of the last sublist had been processed.  Example:
@Lisp
(format @false "Pairs:@tilde@;:@lbrace@; <@tilde@;S,@tilde@;S>@tilde@;@rbrace@;."
	    '((a 1) (b 2) (c 3)))
     @EV "Pairs: <A,1> <B,2> <C,3>."
@Endlisp

@f[@tilde@;@@@lbrace@;@i[str]@tilde@;@rbrace@;] is similar to @f[@tilde@;@lbrace@;@i[str]@tilde@;@rbrace@;], but instead of
using one argument that is a list, all the remaining arguments
are used as the list of arguments for the iteration.
Example:
@Lisp
(format @false "Pairs:@tilde@;@@@lbrace@; <@tilde@;S,@tilde@;S>@tilde@;@rbrace@;."
	    'a 1 'b 2 'c 3)
     @EV "Pairs: <A,1> <B,2> <C,3>."
@Endlisp
If the iteration is terminated before all the remaining arguments are
consumed, then any arguments not processed by the iteration remain to be
processed by any directives following the iteration construct.

@f[@tilde@;:@@@lbrace@;@i[str]@tilde@;@rbrace@;] combines the features of @f[@tilde@;:@lbrace@;@i[str]@tilde@;@rbrace@;] and @f[@tilde@;@@@lbrace@;@i[str]@tilde@;@rbrace@;].
All the remaining arguments
are used, and each one must be a list.
On each iteration, the next argument is used as a list of arguments to @i[str].
Example:
@Lisp
(format @false "Pairs:@tilde@;:@@@lbrace@; <@tilde@;S,@tilde@;S>@tilde@;@rbrace@;."
	    '(a 1) '(b 2) '(c 3))
     @EV "Pairs: <A,1> <B,2> <C,3>."
@Endlisp

Terminating the repetition construct with @f[@tilde@;:⎇] instead of @f[@tilde@;@rbrace@;]
forces @i[str] to be processed at least once, even if the initial
list of arguments is null (however, it will not override an explicit
prefix parameter of zero).

If @i[str] is empty, then an argument is used as @i[str].  It must be a string
and precede any arguments processed by the iteration.  As an example,
the following are equivalent:
@Lisp
(apply #'format stream string arguments)
(format stream "@tilde@;1{@tilde@;:⎇" string arguments)
@Endlisp
This will use @f[string] as a formatting string.  The @f[@tilde@;1{] says it will
be processed at most once, and the @f[@tilde@;:⎇] says it will be processed at least once.
Therefore it is processed exactly once, using @f[arguments] as the arguments.
This case may be handled more clearly by the @f[@tilde?] directive,
but this general feature of @f[@tilde@;@lbrace@;]
is more powerful than @f[@tilde?].
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;@rbrace@;]@\@}
This terminates a @f[@tilde@;@lbrace@;].  It is an error elsewhere.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;@i[mincol],@i[colinc],@i[minpad],@i[padchar]<@i[str]@tilde@;>]@\@}
@i[Justification].
@Index"@f'@tilde@;< '(justification) format directive"
This justifies the text produced by processing @i[str]
within a field at least @i[mincol] columns wide.  @i[str]
may be divided up into segments with @f[@tilde@;;], in which case the
spacing is evenly divided between the text segments.

With no modifiers, the leftmost text segment is left justified in the
field, and the rightmost text segment right justified;  if there is
only one text element, as a special case, it is right justified.
The @f[:] modifier causes
spacing to be introduced before the first text segment;  the @f[@@]
modifier causes spacing to be added after the last.
The @i[minpad] parameter (default @f[0]) is the minimum number of
padding characters to be output between each segment.
The padding character is specified by @i[padchar],
which defaults to the space character.
If the total width needed to satisfy these constraints is greater
than @i[mincol], then the width used is @i[mincol]+@i[k]*@i[colinc]
for the smallest possible non-negative integer value @i[k];
@i[colinc] defaults to @f[1], and @i[mincol] defaults to @f[0].

Examples:
@Lisp
(format @false "@tilde@;10<foo@tilde@;;bar@tilde@;>")          @EV  "foo    bar"
(format @false "@tilde@;10:<foo@tilde@;;bar@tilde@;>")         @EV  "  foo  bar"
(format @false "@tilde@;10:@@<foo@tilde@;;bar@tilde@;>")        @EV  "  foo bar "
(format @false "@tilde@;10<foobar@tilde@;>")            @EV  "    foobar"
(format @false "@tilde@;10:<foobar@tilde@;>")           @EV  "    foobar"
(format @false "@tilde@;10@@<foobar@tilde@;>")           @EV  "foobar    "
(format @false "@tilde@;10:@@<foobar@tilde@;>")          @EV  "  foobar  "
@Endlisp

Note that @i[str] may include @f[format] directives.
All the clauses in @i[str] are processed in order;
it is the resulting pieces of text that are justified.

The @f[@tilde@;↑] directive may be used to terminate processing of the
clauses prematurely, in which case only the completely processed clauses
are justified.

If the first clause of a @f[@tilde@;<] is terminated with @f[@tilde@;:;] instead of
@f[@tilde@;;], then it is used in a special way.  All of the clauses are
processed (subject to @f[@tilde@;↑], of course), but the first one is not used
in performing the spacing and padding.  When the padded result has been
determined, then if it will fit on the current line of output, it is
output, and the text for the first clause is discarded.  If, however, the
padded text will not fit on the current line, then the text segment for
the first clause is output before the padded text.  The first clause
ought to contain a newline (such as a @f[@tilde@;%] directive).  The first
clause is always processed, and so any arguments it refers to will be
used; the decision is whether to use the resulting segment of text, not
whether to process the first clause.  If the @f[@tilde@;:;] has a prefix
parameter @i[n], then the padded text must fit on the current line with
@i[n] character positions to spare to avoid outputting the first clause's
text.  For example, the control string
@Lisp
"@tilde@;%;; @tilde@;@lbrace@;@tilde@;<@tilde@;%;; @tilde@;1:; @tilde@;S@tilde@;>@tilde@;↑,@tilde@;@rbrace@;.@tilde@;%"
@Endlisp
can be used to print a list of items separated by commas without
breaking items over line boundaries, beginning each line with
@f[;; ].  The prefix parameter @f[1] in @f[@tilde@;1:;] accounts for the width of the
comma that will follow the justified item if it is not the last
element in the list, or the period if it is.  If @f[@tilde@;:;] has a second
prefix parameter, then it is used as the width of the line,
thus overriding the natural line width of the output stream.  To make
the preceding example use a line width of 50, one would write
@Lisp
"@tilde@;%;; @tilde@;@lbrace@;@tilde@;<@tilde@;%;; @tilde@;1,50:; @tilde@;S@tilde@;>@tilde@;↑,@tilde@;@rbrace@;.@tilde@;%"
@Endlisp

If the second argument is not specified, then @f[format] uses the
line width of the output stream.
If this cannot be determined (for example, when producing a string result),
then @f[format] uses @f[72] as the line length.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;>]@\@}
Terminates a @f[@tilde@;<].  It is an error elsewhere.
@End[Multiple]

@Begin[Multiple, Spread 0.3]
@f[@tilde@;↑]@\@Index"@f'@tilde@;↑ '(@i[loop escape]) format directive"@}
@i[Up and out].
This is an escape construct.  If there are no more arguments remaining to
be processed, then the immediately enclosing @f[@tilde@;@lbrace@;] or @f[@tilde@;<] construct
is terminated.  If there is no such enclosing construct, then the entire
formatting operation is terminated.  In the @f[@tilde@;<] case, the formatting
@i[is] performed, but no more segments are processed before doing the
justification.  The @f[@tilde@;↑] should appear only at the @i[beginning] of a
@f[@tilde@;<] clause, because it aborts the entire clause it appears in (as well
as all following clauses).
@f[@tilde@;↑] may appear anywhere in a @f[@tilde@;@lbrace@;]
construct.
@Lisp
(setq donestr "Done.@tilde@;↑  @tilde@;D warning@tilde@;:P.@tilde@;↑  @tilde@;D error@tilde@;:P.")
(format @false donestr) @EV "Done."
(format @false donestr 3) @EV "Done.  3 warnings."
(format @false donestr 1 5) @EV "Done.  1 warning.  5 errors."
@Endlisp

If a prefix parameter is given, then termination occurs if the parameter
is zero.  (Hence @f[@tilde@;↑] is equivalent to @f[@tilde@;#↑].)  If two
parameters are given, termination occurs if they are equal.  If three
parameters are given, termination occurs if the first is less than or
equal to the second and the second is less than or equal to the third.
Of course, this is useless if all the prefix parameters are constants; at
least one of them should be a @f[#] or a @f[V] parameter.

If @f[@tilde@;↑] is used within a @f[@tilde@;:@lbrace@;] construct, then it merely terminates
the current iteration step (because in the standard case it tests for
remaining arguments of the current step only); the next iteration step
commences immediately.  To terminate the entire iteration process,
use @f[@tilde@;:↑].

If @f[@tilde@;↑] appears within a control string being processed
under the control of a @f[@tilde@;?] directive, but not within
any @f[@tilde@;@lbrace@;] or @f[@tilde@;<] construct within that string,
then the string being
processed will be terminated, thereby ending processing
of the @f[@tilde@;?] directive.  Processing then
continues within the string
containing the @f[@tilde@;?] directive at the point following that directive.

If @f[@tilde@;↑] appears within a @f{@tilde@;@lbracket@;⎇ or @f[@tilde@;(] construct,
then all the commands up to the @f[@tilde@;↑] are properly selected
or case-converted, the @f{@tilde@;@lbracket@;⎇ or @f[@tilde@;(] processing is terminated,
and the outward search continues for a @f[@tilde@;@lbrace@;] or @f[@tilde@;<] construct
to be terminated.  For example:
@lisp
(setq tellstr "@tilde@;@@(@tilde@;@@@lbracket@;@tilde@;R@tilde@;@rbracket@;@tilde@;↑ @tilde@;A.@tilde@;)")
(format @false tellstr 23) @EV "Twenty-three."
(format @false tellstr nil "losers") @EV "Losers."
(format @false tellstr 23 "losers") @EV "Twenty-three losers."
@endlisp

Here are some examples of the use of @f[@tilde@;↑] within a @f[@tilde@;<] construct.
@Lisp
(format @false "@tilde@;15<@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;>" 'foo)
	@EV  "            FOO"
(format @false "@tilde@;15<@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;>" 'foo 'bar)
	@EV  "FOO         BAR"
(format @false "@tilde@;15<@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;;@tilde@;↑@tilde@;S@tilde@;>" 'foo 'bar 'baz)
	@EV  "FOO   BAR   BAZ"
@Endlisp
@End[Multiple]
@End[Description]

@Incompatibility{The @f[@tilde@;Q] directive and user-defined directives have been
omitted here, as well as control lists (as opposed to strings),
which are rumored to be changing in meaning.⎇

@Section[Querying the User]
@Index[querying the user]
@Index[yes-or-no functions]

The following functions provide a convenient and consistent interface for
asking questions of the user.  Questions are printed and the answers are
read using the stream @Varref[query-io], which normally is synonymous with
@Varref[terminal-io] but can be rebound to another stream for special
applications.

@Defun[Fun {y-or-n-p⎇, Args {@optional @i[format-string] @rest @i[arguments]⎇]
This predicate is for asking the user a question whose answer is either
``yes'' or ``no.''  It types out a message (if supplied), reads an answer
in some implementation-dependent manner (intended to be short and simple,
like reading a single character such as @f[Y] or @f[N]), and is
true if the answer was ``yes'' or false if the answer was ``no.''

If the @i[format-string] argument is supplied and not @false,
then a @Funref[fresh-line] operation is performed; then
a message is printed as if the @i[format-string] and @i[arguments]
were given to @Funref[format].
Otherwise it is assumed that any message has already been printed
by other means.
If you want a question mark at the end of the message,
you must put it there yourself; @f[y-or-n-p] will not add it.
However, the message should not contain an explanatory note such
as @f[(Y or N)], because the nature of the interface provided for
@f[y-or-n-p] by a given implementation might not involve typing a
character on a keyboard; @f[y-or-n-p] will provide such a note
if appropriate.

All input and output are performed using the stream in the global
variable @varref[query-io].

Here are some examples of the use of @f[y-or-n-p]:
@Lisp
(y-or-n-p "Produce listing file?")
(y-or-n-p "Cannot connect to network host }S.  Retry?" host)
@Endlisp

@f[y-or-n-p] should only be used for questions that the user knows
are coming or in situations where the user is known to be waiting for
a response of some kind.
If the user is unlikely to anticipate the question,
or if the consequences of the answer might be grave and irreparable,
then @f[y-or-n-p] should not be used because the user might type ahead
and thereby accidentally answer the question.
For such questions as ``Shall I delete all of your files?'' it is better to use
@f[yes-or-no-p].
@Enddefun

@Defun[Fun {yes-or-no-p⎇, Args {@optional @i[format-string] @rest @i[arguments]⎇]
This predicate, like @f[y-or-n-p], is for asking the user a question
whose answer is either ``Yes'' or ``No.''  It types out a message (if
supplied), attracts the user's attention (for example, by ringing
the terminal's bell), and reads a reply in some
implementation-dependent manner.  It is intended that the reply require
the user to take more action than just a single keystroke, such as typing
the full word @f[yes] or @f[no] followed by a newline.

If the @i[format-string] argument is supplied and not @false,
then a @Funref[fresh-line] operation is performed; then
a message is printed as if the @i[format-string] and @i[arguments]
were given to @Funref[format].
Otherwise it is assumed that any message has already been printed
by other means.
If you want a question mark at the end of the message,
you must put it there yourself; @f[yes-or-no-p] will not add it.
However, the message should not contain an explanatory note such
as @f[(Yes or No)] because the nature of the interface provided for
@f[yes-or-no-p] by a given implementation might not involve typing the
reply on a keyboard; @f[yes-or-no-p] will provide such a note
if appropriate.

All input and output are performed using the stream in the global
variable @varref[query-io].

To allow the user to answer a yes-or-no question with a single
character, use @f[y-or-n-p].  @f[yes-or-no-p] should be
used for unanticipated or momentous questions;
this is why it attracts attention
and why it requires a multiple-action sequence to answer it.
@Enddefun